Report a malicious asset via API

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.

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.

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.

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

Endpoint

POST https://api.opensourcemalware.com/functions/v1/submit-threat-report

Required headers

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 below.
`threat_description`	string	A clear explanation of the malicious behavior. See writing a strong description.

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

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

401 — No Authorization header

{ "error": "Authorization required" }

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

{ "error": "Invalid API token" }

429 — IP rate limit

{ "error": "Rate limit exceeded for your IP address. Please try again later." }

429 — Submission rate limit (per hour)

{ "error": "Rate limit exceeded. Maximum 10 submissions per hour." }

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

403 — New-user unverified cap

{
  "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

{ "error": "Method not allowed" }

400 — Missing required fields

{ "error": "Missing required fields: report_type, resource_identifier, and threat_description are required" }

409 — Duplicate package in registry

{
  "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

{
  "error": "Failed to check for existing package",
  "details": "<postgres error message>"
}

500 — Threat insert failed

{
  "error": "Failed to create threat report",
  "details": "<postgres error message>"
}

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

{
  "error": "Failed to create threat details",
  "details": "<postgres error message>"
}

500 — Catch-all

{
  "error": "Internal server error",
  "details": "<exception message>"
}

Examples

Package report

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

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

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"]
  }'

Overview

Free Endpoints

Paid Endpoints

Endpoint

Request body

Required fields

Optional fields

Resource identifier format

IOC formatting in `payload_description`

Responses

201 — Success

401 — No Authorization header

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

429 — IP rate limit

429 — Submission rate limit (per hour)

403 — New-user unverified cap

405 — Method not allowed

400 — Missing required fields

409 — Duplicate package in registry

500 — Existing-package lookup failed

500 — Threat insert failed

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

500 — Catch-all

Examples

​Endpoint

​Request body

​Required fields

​Optional fields

​Resource identifier format

​IOC formatting in payload_description

​Responses

​201 — Success

​401 — No Authorization header

​401 — Invalid API token (osm_...)

​429 — IP rate limit

​429 — Submission rate limit (per hour)

​403 — New-user unverified cap

​405 — Method not allowed

​400 — Missing required fields

​409 — Duplicate package in registry

​500 — Existing-package lookup failed

​500 — Threat insert failed

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

​500 — Catch-all

​Examples

Endpoint

Request body

Required fields

Optional fields

Resource identifier format

IOC formatting in `payload_description`

Responses

201 — Success

401 — No Authorization header

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

429 — IP rate limit

429 — Submission rate limit (per hour)

403 — New-user unverified cap

405 — Method not allowed

400 — Missing required fields

409 — Duplicate package in registry

500 — Existing-package lookup failed

500 — Threat insert failed

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

500 — Catch-all

Examples