> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opensourcemalware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Report a malicious asset via API

> Automate submission of threat reports from your own tooling instead of the web UI.

The `submit-threat-report` endpoint lets you submit threat reports programmatically without using the web interface. Submitted reports enter the community verification process and are only published after passing a human review.

Use this endpoint to:

* **Automate reporting from your tooling:** Flag suspicious assets the moment your  detection systems identify them, without switching to the web UI.
* **Integrate with security pipelines:** Trigger submissions directly from CI/CD workflows, dependency scanners, or SIEM alerts.
* **Contribute at scale:** Research teams and Research Partners can submit structured threat reports in bulk via API.

<Note>
  Reports go through the community verification process before they are published to the database. This review ensures data quality and prevents false positives. You can track the status of your submissions from your [profile](https://opensourcemalware.com/my-submissions).
</Note>

<Warning>
  New users are limited to three reports. Once they're verified, this limit is removed. If you try to submit more than three reports before your initial three submissions are approved, you will receive a 403 error.
</Warning>

For guidance on writing high-quality threat reports — including what evidence to include and how to describe threat behavior — see the [reporting guidelines](/reporting/guidelines).

## Endpoint

```text theme={null}
POST https://api.opensourcemalware.com/functions/v1/submit-threat-report
```

**Required headers**

```text theme={null}
Authorization: Bearer osm_your_token
Content-Type: application/json
```

## Request body

### Required fields

| Field                 | Type   | Description                                                                                                                    |
| --------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `report_type`         | string | `"package"` \| `"repository"` \| `"url"` \| `"domain"` \| `"ip"` \| `"wallet"` \| `"container"`                                |
| `resource_identifier` | string | The identifier for the asset being reported. See [format by report type](#resource-identifier-format) below.                   |
| `threat_description`  | string | A clear explanation of the malicious behavior. See [writing a strong description](/reporting/guidelines#required-information). |

### Optional fields

| Field                 | Type   | Description                                                                                                                                                   |     |
| --------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- |
| `package_name`        | string | Name of the package as it appears in the registry.                                                                                                            |     |
| `registry`            | string | Package registry, e.g. `"npm"`, `"pypi"`, `"rubygems"`.                                                                                                       |     |
| `publisher`           | string | Publisher username, email, or organization associated with the threat.                                                                                        |     |
| `payload_description` | string | Technical details about what the malicious code does. Supports Markdown — use headers, bullet lists, and inline code to structure IOCs and behavioral detail. |     |
| `severity_level`      | string | `"critical"` \| `"high"` \| `"medium"` \| `"low"`                                                                                                             |     |
| `evidence_references` | string | URLs to supporting evidence, separated by \`                                                                                                                  | \`. |
| `contact_email`       | string | Your email address for follow-up.                                                                                                                             |     |
| `tags`                | array  | Categorization labels such as `"postinstall-hook"`, `"credential-theft"`, or a campaign name.                                                                 |     |
| `version_info`        | string | Affected version numbers only, comma-separated (e.g. `"1.0.1, 2.1.2, 3.0.3"`). Do not include prose — context belongs in `threat_description`.                |     |
| `first_seen`          | string | ISO 8601 timestamp of when the threat was first observed or published.                                                                                        |     |
| `last_seen`           | string | ISO 8601 timestamp of the most recent observation.                                                                                                            |     |
| `osv_advisory_url`    | string | Link to a corresponding OSV advisory, if one exists.                                                                                                          |     |
| `contributors`        | array  | Other researchers who contributed to this report.                                                                                                             |     |
| `download_count`      | number | Download statistics for the reported asset at the time of discovery.                                                                                          |     |

### Resource identifier format

The value of `resource_identifier` depends on `report_type`:

| Report type  | Expected format                            | Example                               |
| ------------ | ------------------------------------------ | ------------------------------------- |
| `package`    | Package name as it appears in the registry | `@scope/package-name`                 |
| `repository` | Host and path, no protocol                 | `github.com/user/repo`                |
| `url`        | Full URL                                   | `https://example.com/payload`         |
| `domain`     | Bare domain                                | `evil-c2-server.com`                  |
| `ip`         | IP address                                 | `192.0.2.1`                           |
| `wallet`     | Wallet address                             | `1A1zP1eP5QGefi2DMPTfTL5SLmv7Divf Na` |
| `container`  | Image reference                            | `docker.io/evil/image:latest`         |

### IOC formatting in `payload_description`

When including network indicators, file hashes, or other IOCs in `payload_description`, follow standard defanging conventions to prevent accidental execution or link-following:

* URLs: replace `https://` with `hxxps://`
* Dots in domains and IPs: replace `.` with `[.]`

Example: `hxxps://malicious[.]example[.]com/payload`

`payload_description` renders as Markdown in the OSM web UI. Use headers (`##`), bullet lists, and inline code backticks to structure behavioral detail and IOCs for readability.

## Responses

### 201 — Success

```json theme={null}
{
  "message": "Threat report submitted successfully",
  "threat_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "pending"
}
```

### 401 — No Authorization header

```json theme={null}
{ "error": "Authorization required" }
```

### 401 — Invalid API token (`osm_...`)

```json theme={null}
{ "error": "Invalid API token" }
```

### 429 — IP rate limit

```json theme={null}
{ "error": "Rate limit exceeded for your IP address. Please try again later." }
```

### 429 — Submission rate limit (per hour)

```json theme={null}
{ "error": "Rate limit exceeded. Maximum 10 submissions per hour." }
```

<Note>
  10/hour for Free users. Limit may be increased by an admin.
</Note>

### 403 — New-user unverified cap

```json theme={null}
{
  "error": "New users are limited to 3 unverified reports. You currently have 3 unverified reports. Once 3 of your reports are verified, this limit will be removed.",
  "verified_reports": 0,
  "unverified_reports": 3
}
```

### 405 — Method not allowed

```json theme={null}
{ "error": "Method not allowed" }
```

### 400 — Missing required fields

```json theme={null}
{ "error": "Missing required fields: report_type, resource_identifier, and threat_description are required" }
```

### 409 — Duplicate package in registry

```json theme={null}
{
  "error": "A threat report for this package in this registry already exists. Please use the \"Update Report\" functionality to modify the existing report.",
  "existingThreatId": "<uuid>",
  "packageName": "<package-name>",
  "registry": "npm",
  "status": "verified"
}
```

### 500 — Existing-package lookup failed

```json theme={null}
{
  "error": "Failed to check for existing package",
  "details": "<postgres error message>"
}
```

### 500 — Threat insert failed

```json theme={null}
{
  "error": "Failed to create threat report",
  "details": "<postgres error message>"
}
```

### 500 — Threat details insert failed (threat was rolled back)

```json theme={null}
{
  "error": "Failed to create threat details",
  "details": "<postgres error message>"
}
```

### 500 — Catch-all

```json theme={null}
{
  "error": "Internal server error",
  "details": "<exception message>"
}
```

## Examples

**Package report**

```text theme={null}
curl -X POST "https://api.opensourcemalware.com/functions/v1/submit-threat-report" \
  -H "Authorization: Bearer osm_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "report_type": "package",
    "resource_identifier": "malicious-package",
    "threat_description": "Package contains a postinstall hook that downloads and executes a cryptocurrency miner.",
    "package_name": "malicious-package",
    "registry": "npm",
    "version_info": "1.0.0, 1.0.1, 1.0.2",
    "severity_level": "critical",
    "tags": ["cryptocurrency", "miner", "postinstall-hook"]
  }'
```

**Repository report**

```text theme={null}
curl -X POST "https://api.opensourcemalware.com/functions/v1/submit-threat-report" \
  -H "Authorization: Bearer osm_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "report_type": "repository",
    "resource_identifier": "github.com/malicious-user/evil-repo",
    "threat_description": "Repository contains an info-stealer targeting GitHub Actions secrets and AWS credentials.",
    "publisher": "malicious-user",
    "severity_level": "high",
    "tags": ["infostealer", "credential-theft"]
  }'
```

**Domain report**

```text theme={null}
curl -X POST "https://api.opensourcemalware.com/functions/v1/submit-threat-report" \
  -H "Authorization: Bearer osm_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "report_type": "domain",
    "resource_identifier": "evil-c2-server.com",
    "threat_description": "C2 server receiving exfiltrated credentials from trojanized npm packages in the jagreehal ecosystem.",
    "severity_level": "critical",
    "tags": ["c2", "credential-theft"]
  }'
```