/malware-notifications

A REST API to store and list malware detection notifications

Primary LanguageJavaMIT LicenseMIT

Malware Notifications

Table of Contents

  1. Introduction
  2. Configuration
  3. Development and Running
  4. Docker
  5. API
  6. Contributing
  7. License

Introduction

Malware Notifications is a web backend application. It provides APIs to store and list results of malware scans on devices.

It uses

  • Spring Boot 2.7.3
  • Java 18
  • PostgreSQL for database
  • Flyway to manage DB schemas
  • Spring Data JPA to database access
  • JUnit 5 and Testcontainers for testing

Configuration

There is no need for a manual configuration as default values are enough to run Malware Notifications out-of-the-box (as long as database is available, see Docker section). However, if you wish to make your own configuration, you can do so via application.properties. You can also override config values with following environment variables.

Variable Name Data Type Description Required
DB_HOST String Host address of application database No, defaults to localhost
DB_PORT Integer Port of application database No, defaults to 5432
DB_NAME String Name of application database No, defaults to malware-notifications
DB_USER String User of application database No, defaults to malware-notifications
DB_PASSWORD String Password of application database No, defaults to malware-notifications

Development and Running

Malware Notifications is built with Gradle. Standard Gradle tasks like clean, compile, run and test can be used.

If you don't have Gradle installed, you can replace gradle commands with ./gradlew to use Gradle wrapper.

To run the application locally:

gradle run --console=plain

Docker

Malware Notifications can be built and run in Docker with its database. To build and run using docker-compose:

docker-compose up -d --build

This will create database container, build the application image, create application container and run everything together in detached mode.

Docker builds can also be customized as follows:

Variable Name Data Type Description Required
PORT Integer Port to bind in the host machine for the application No, defaults to 8080
DB_PORT Integer Port to bind in the host machine for the database No, defaults to 5432

This way, when you run the stack as following

PORT=80 DB_PORT=1234 =docker-compose up -d --build

you'll be able to access the application at http://localhost:80 and the database at jdbc:postgresql://localhost:1234/malware-notifications.

API Docs

Malware Notifications provide OpenAPI documentation and a Swagger UI to browse them. After running the application, you may go to /swagger-ui.html to see the documentation.

Here is an overview of the APIs:

Method URL Link
GET /detections Jump
POST /detections Jump

Errors return an error Json in following format:

{
  "message": "An unexpected error occurred",
  "details": "Some details about the error"
}

with a non-OK HTTP status code.

All successful responses will have 200 OK status unless explicitly mentioned.

GET /detections

This endpoint can be used to list previously stored malware detections. It supports pagination, sorting and some basic filtering.

Parameters

Parameter Data Type Description Required Default Value
page Integer Page number to get No 1
perPage Integer Number of items to get in a page No 10
sortBy One of [DEVICE_TYPE, TIME, TYPE, APP_NAME, APP_TYPE] Field to sort by No TIME
ascending Boolean Whether or not sorting is ascending No false when sorting by TIME and to true for other sorts
type One of [NEW, RESOLVED] Type of malware detections to get No defaults to nothing to get all types

Example Successful Response

{
  "data": [
    {
      "detection": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "time": "2022-08-31T17:30:16.623Z",
        "type": "NEW",
        "appName": "Facebook",
        "appType": "Social"
      },
      "device": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "type": "IOS",
        "model": "Apple iPhone 13 Pro",
        "os": "iOS 15.4"
      }
    }
  ],
  "page": 1,
  "totalPages": 1
}

POST /detections

This endpoint can be used to process a malware scan coming from a device and store given detections.

Request Payload

{
  "device": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "type": "IOS",
    "model": "Apple iPhone 13 Pro",
    "os": "iOS 15.4"
  },
  "time": "2022-08-31T17:32:53.794Z",
  "detections": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "time": "2022-08-31T17:32:53.794Z",
      "type": "NEW",
      "appName": "Facebook",
      "appType": "Social"
    },
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "time": "2022-08-31T17:33:53.794Z",
      "type": "RESOLVED"
    }
  ]
}
  • Device and detection data are updated if they already exist for given ids.
  • RESOLVED detections don't have app details. They are assumed to be already stored with same id before.

Example Successful Response

200 OK with no data

Contributing

All contributions are welcome. Please feel free to send a pull request. Thank you.

License

Malware Notifications is licensed with MIT License.