IoC Upload via API

The Maltiverse API provides a structured way for users to upload and manage Indicators of Compromise (IoCs) such as IPv4 addresses, hostnames, URLs, and samples (identified by hashes like MD5, SHA1, SHA256, SHA512). This article details how to use the Maltiverse API, specifically focusing on uploading IoCs, based on the OpenAPI specification version 3.0.0.

Prerequisites #

To use the Maltiverse API, you need:

• API access with a valid bearer token for authentication. You can get you API Key in the user profile
• Familiarity with HTTP methods (GET, PUT, POST, DELETE).
• Knowledge of IoC types and their respective formats.

Authentication #

All API requests must be authenticated using a bearer token (JWT format). Include the token in the Authorization header of your HTTP request. (This can be a temporary authorization token or the API KEY)

API Endpoints for Uploading IoCs #

1. IPv4 Address #

• Endpoint: /ip/{ipv4}
• Method: PUT
• Description: Uploads an IPv4 address IoC to the system.
• Parameter: IPv4 address in the path.
• Request Body: An IpItem object containing details about the IPv4 IoC.

2. Hostname #

• Endpoint: /hostname/{hostname}
• Method: PUT
• Description: Adds a hostname IoC to the system.
• Parameter: Hostname in the path.
• Request Body: A HostnameItem object containing details about the hostname IoC.

3. URL #

• Endpoint: /url/{urlchecksum}
• Method: PUT
• Description: Uploads a URL IoC, identified by its SHA256 checksum.
• Parameter: URL checksum in the path.
• Request Body: A UrlItem object containing URL IoC details.

4. Sample (File Hash) #

• Endpoint: /sample/{sha256}
• Method: PUT
• Description: Uploads a sample IoC, identified by its SHA256 hash.
• Parameter: SHA256 hash in the path.
• Request Body: A SampleItem object with details about the sample.

JSON Construction #

The JSON you upload needs to be compliant with the structure defined in the API specification.

The field blacklist.source must contain the name of your team in Maltiverse, as you only can publish IoCs under your attribution

Response Handling #

Upon successful upload, the API typically returns a status code of 200 (OK) or 201 (Created). If there are issues with the request, such as invalid IoC format or authentication problems, the API will respond with appropriate HTTP status codes (e.g., 400 Bad Request, 401 Unauthorized, 500 Internal Server Error).

Example Request (Uploading an IPv4 Address) #

You can find a working script example in Maltiverse Github repository:

https://github.com/maltiverse/maltiverse-script-examples/blob/main/scripts/upload/upload_ip.py

Conclusion #

The Maltiverse API offers a comprehensive and secure way to upload various types of IoCs. By utilizing specific endpoints and adhering to the required formats, users can effectively contribute to and utilize the Maltiverse threat intelligence platform.

For complete details and additional functionalities, refer to the Maltiverse API documentation and the OpenAPI specification provided.