> ## 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.
# API Response Fields
> Reference for every field returned across the API endpoints and tips on how to use them.
This page covers every field returned by the `check-malicious`, `query-latest`, `threat-feed`, `threat-data`, and `query-by-username` endpoints. Fields are grouped by type to make it easier to understand how related fields work together.
## Asset identity
These fields describe what the asset is and where it lives. Together they give you enough information to locate the asset in your environment and act on it.
### `resource_identifier`
**Type:** string · **Returned by:** `check-malicious`, `query-latest`, `threat-feed`, `query-by-username`
The name of the asset that was queried or flagged — the package name, URL, domain, IP address, or repository URL.
**How to use it:** Use this exact string to add to a blocklist or firewall rule (Exception: If the asset is a package, use the `package_name` field instead.) In alerts, this populates the "what was detected" field. During incident response, search your environment for any use of this identifier to scope exposure. Refer to `package_name` for packages.
### `package_name`
**Type:** string · **Returned by:** `check-malicious`,`query-latest`, `threat-feed`, `threat-data`, `query-by-username`
While similar to `resource_identifier`, this field is only for packages. It is an ecosystem-formatted package name that is designed to be recognized by the corresponding ecosystem.
**How to use it:** Use in alert titles, notifications, and reports where a precise match is required. When cross-referencing against a dependency manifest or inventory / SBOM, match on `package_name` rather than `resource_identifier`.
### `id` / `threat_id` / `source_id`
**Type:** string (UUID) · **Returned by:** all endpoints
The unique identifier (UUID) for a threat record in the OpenSourceMalware database.
**How to use it:** Use as the primary key for deduplication when ingesting from multiple endpoints. Pass to `threat-data` to retrieve the full threat record and IOCs for any threat surfaced by another endpoint.
### `version_info`
**Type:** string · **Returned by:** `check-malicious`, `query-latest`, `threat-feed`
The specific version(s) of a package or container image that are malicious.
* `null` or blank value means all versions are affected. This is the most common return for this field because most malicious assets have always been owned by threat actors.
* Can display a single version (e.g. 1.0.1-security), a series of versions separated by commas (e.g. 1.1.2, 5.6.0), or a block of versions (e.g. 1.0.0 - 3.0.0).
**How to use it:** When setting up a blocklist or cross-referencing against a dependency manifest or inventory / SBOM, match on both the package name and version to avoid false positives on unaffected releases.
### `report_type`
**Type:** string · **Returned by:** `check-malicious`, `query-latest`, `threat-feed`, `threat-data`
This field is the category of the `resource_identifier`. Values include:
* `package`
* `container`
* `repository`
* `url`
* `domain`
* `ip`
* `wallet`
**How to use it:** Use to route the response to the right blocking mechanism or team. For example, package findings belong in your private registry or dependency scanner; domain and IP findings belong in your network controls; container findings belong in your registry policy. In alerting pipelines, use this field to assign findings to the right team — for example AppSec for packages.
### `ecosystem`
**Type:** string · **Returned by:** all endpoints
This field describes the ecosystem (e.g. npm, PyPI, AI skill) that the `resource_identifier` belongs to. It is a more fine-grain version of `report-type`.
**How to use it:** Scope blocking and scanning actions to the correct ecosystem. For example, npm and PyPI can contain packages with identical names. Instead of blocking all packages with a given name, blocking by `ecosystem` reduces false positives. In alerting workflows, use this field to route findings to the right team or playbook.
### `username`
**Type:** string · **Returned by:** `query-by-username`
The publisher or author username related to a `resource_identifier`.
**How to use it:** A single compromised or malicious account may be responsible for multiple threats. During incident response, pivot from a malicious package to its publisher to surface all other packages that account has released. Use in threat actor profiling to track known malicious publishers across ecosystems over time.
***
## Verdict & status
These fields carry the core signals that tell you whether a `resource_identifier` is confirmed malicious and whether the record has been verified by OpenSourceMalware.
### `malicious`
**Type:** boolean · **Returned by:** `check-malicious`
This field tells you whether the `resource_identifier` you queried is a human-verified threat in the OpenSourceMalware database.
* `malicious: true` = in the database
* `malicious: false` = not in the database
`false` means the resource was not found in the database at the time of the query. It's not a guarantee the asset is safe. Factor `last_scanned_at` into your confidence level for clean results.
**How to use it:** Use as the gate for blocking decisions, SBOM cross-reference results, and alert triggers.
### `status`
**Type:** string · **Returned by:** `threat-feed`
OpenSourceMalware reviews all threat record submissions. This field tells you the review status of the `resource_identifier`:
* `verified` = Has completed a human review
* `unverified` = Is awaiting human review
* `false positive` = A human concluded it's not malicious
* `modified` = An already-verified record is pending human review for an update
**How to use it:** Filter on `verified` to ensure downstream systems only act on confirmed threats, and use `unverified` to identify suspicious assets quickly (especially relevant for account takeovers that rely on automatic upgrades) and consider blocking until the status has changed.
### `scan_result`
**Type:** boolean | null · **Returned by:** `check-malicious`
The result of the most recent analysis by OpenSourceMalware's proprietary detection engine.
* `scan_result: true` = The analysis finds the asset is malicious
* `scan_result: false` = The analysis finds the asset is "suspicious" but not necessarily "malicious"
* `scan_result: null` = OpenSourceMalware hasn't analyzed the asset
**How to use it:** Use alongside `malicious` for additional context on scan state. It may help prioritize next steps.
## Severity & classification
These fields describe how severe the threat is and what type of behavior it exhibits.
### `severity_level`
**Type:** string · **Returned by:** all endpoints
The assessed severity of the threat assigned by the threat reporter (and may be manually adjusted by OpenSourceMalware during verification process). Values are:
* `critical`
* `high`
* `medium`
* `low`
* `informational` (Indicates a human decided the asset isn't malicious but displays characteristics that should concern consumers.)
Unlike CVEs, all malware is dangerous. Don't use `severity` to determine what should/shouldn't be blocked.
**How to use it:** When multiple affected assets are identified simultaneously, use `severity_level` to prioritize remediation order. In alerting pipelines, you can map severity levels to paging vs. non-paging thresholds.
### `tags`
**Type:** array · **Returned by:** `query-latest`, `threat-feed`
Behavioral and categorical labels describing the threat. They fall into several groups, including:
* Describe the malware, e.g. `infostealer`, `cryptostealer`
* Attack type, e.g. `account-takeover`, `typosquat`
* Link to threat actor group, e.g. `dprk`, `teampcp`
* Malware campaign, e.g. `mini-shai-hulud`, `miasma`
**How to use it:** Use to categorize alerts automatically and route them to the appropriate playbook — a `ransomware` tag triggers a different response than `suspicious-metadata`. In your SIEM or SOAR, tag-based routing reduces analyst triage time. For threat research, cluster threats by tag to identify trending TTPs and connect otherwise unrelated packages to the same campaign pattern. You can also search the web UI using tags (e.g. #teampcp)
## Timestamps
OpenSourceMalware returns several timestamp fields with different meanings. Understanding which one to use for each purpose prevents gaps in coverage and incorrect timeline reconstruction.
### `first_seen`
**Type:** timestamp · **Returned by:** `query-latest`, `threat-feed`
Denotes when the asset was originally published (i.e. the first version, whether it was malicious or not). This data may be supplied by the submitter or based on information provided by the registry.
Sometimes registries artifically change the timestamp for when an asset was created. This can cause challenges in identifying the original timestamp. If `first seen` and `last seen` are the same, this is an indicator that we couldn't obtain the original publication date. In this scenario, do not assume consumption before this data is safe.
**How to use it:** During incident response, compare `first_seen` against your last dependency audit or deployment date — if `first_seen` predates your last review, your exposure window may be longer than expected. You can also as context for potential blast radius assessment alongside `download_count`. A package published recently with a high download count that is now flagged as malicious indicates a fast-moving supply chain attack. For threat research, use the gap between `first_seen` and `created_at` to understand detection latency.
### `created_at`
**Type:** timestamp · **Returned by:** `query-latest`, `threat-feed`, `query-by-username`
When the threat record was first created in the OpenSourceMalware database (prior to verification).
**How to use it:** Useful for retrospective analysis and timeline reconstruction. For most operational workflows, `first_seen` is more meaningful.
### `verified_at`
**Type:** timestamp · **Returned by:** `query-latest`, `threat-feed`
The time when a human reviewer made a judgment on a pending threat report and picked a `status`.
**How to use it:** Use as the authoritative timestamp for feed polling and deduplication. Two poll windows that overlap will return the same records with the same `verified_at` value, making deduplication by this field reliable.
### `published_date`
**Type:** timestamp · **Returned by:** `query-latest`, `threat-feed`
If OpenSourceMalware's propietary detection engine analyzes a specific asset version, this timestamp indicates when that specific version was published.
**How to use it:** This data is informational.
### `last_scan_at` / `last_seen`
**Type:** timestamp · **Returned by:** `check-malicious`, `query-latest`, `threat-feed`
The timestamp for the last time OpenSourceMalware's proprietary detection engine scanned the asset. This analysis is performed on nearly all assets, but in some edge cases you may see `null` if the scan was bypassed.
**How to use it:** A clean result (`malicious: false`) is only as reliable as its scan date, so you can use this field to determine data freshness. If it's old or `null`, the resource may not have been recently evaluated.
### `updated_at`
**Type:** timestamp · **Returned by:** `query-latest`, `threat-feed`
Only appears when a threat record has been modified.
**How to use it:** Use to detect when a previously ingested threat has been enriched with new information. Re-ingest records where `updated_at` is newer than your last ingestion timestamp to ensure your blocklists and detection rules reflect the latest IOCs and descriptions.
## Threat intelligence
These fields contain the actual intelligence content: What the malware does, how it behaves, and what indicators it leaves behind.
### `threat_description`
**Type:** string · **Returned by:** `query-latest`, `threat-feed`, `threat-data`, `query-by-username`
A human-readable summary of the `resource_identifier`, which may include the type of attack, what the malware does, and campaign/attackerd details. This information is provided by the person who submitted the threat report and may be modified by any OpenSourceMalware user (subject to admin approval).
**How to use it:** Include in alert notifications so developers and analysts have immediate context without needing to pivot to the OpenSourceMalware UI. During incident response, use to quickly understand the nature of the threat. For research and reporting, this is the primary source for threat summaries and executive briefings.
### `payload_description`
**Type:** string · **Returned by:** `query-latest`, `threat-feed`
A technical breakdown of the malicious payload including entry points, behavioral findings, and unstructored IOCs (see the IOCs section for structured IOCs). This information is provided by the person who submitted the threat report and may be modified by any OpenSourceMalware user (subject to admin approval).
**How to use it:** Use for detection rule authoring — entry points and behavioral patterns translate directly into YARA rules, Sigma rules, or EDR queries. During triage, use to determine whether an alert represents active exploitation or just the presence of a malicious file. This field is more technical than `threat_description` and is primarily useful for incident responders, security engineers and threat hunters.
### `IOCs`
**Type:** array · **Returned by:** `threat-data`
Structured IOCs associated with a `threat_id` (UUID), which were extracted by OpenSourceMalware's proprietary research. Each IOC object contains the following fields:
| Sub-field | Type | Description |
| ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------ |
| `ioc_type` | string | The category of the indicator: `domain`, `url`, `ip`, `c2_server`, `file_hash_sha256`, `email_address`, and others |
| `value` | string | The raw indicator — the exact string to block or detect |
| `confidence_level` | string | Confidence in the indicator: `high`, `medium`, or `low` |
| `description` | string | Contextual note about what the indicator represents (e.g. "C2 exfiltration endpoint") |
**How to use it:** IOCs are the primary input for incident response and network-level/endpoint blocking. Add C2 domains and IPs to your firewall, DNS filter, or proxy blocklist. Feed hashes into your EDR blocklist. Use `ioc_type` to route each indicator to the right control. Use `confidence_level` to tier your response — high-confidence indicators warrant automatic blocking; medium-confidence may warrant alerting-only rules to reduce false positives. In your SIEM, create detection rules for each IOC to identify whether any have already appeared in your telemetry — a hit means active exploitation, not just exposure.
### `ioc_count`
**Type:** integer · **Returned by:** `threat-data`
The total number of IOCs associated with the `threat_id`.
**How to use it:** Use as a quick signal for complexity and blast radius. A high IOC count suggests a sophisticated, multi-stage threat with broad infrastructure. Use for pagination planning if your ingestion pipeline processes IOCs individually.
### `malicious_dependencies`
**Type:** array · **Returned by:** `query-latest`, `threat-feed`
If the payload sits in a transitive dependency (could be a package or a URL), this field contains the `resource_identifier` for that related asset.
**How to use it:** Expands the scope of action beyond the initially flagged asset. If a package depends on a malicious package, both need to be addressed. Use to ensure your blocklist and SBOM cross-reference catches the full dependency chain rather than just the top-level flagged asset.
## Scan metadata
These fields provide quantitative context about the threat — how many times it has been seen, scanned, and downloaded.
### `scan_count`
**Type:** integer · **Returned by:** `check-malicious`
The number of times OpenSourceMalware has analyzed this specific resource. A new scan may be triggered if a new version of the resource has been published.
**How to use it:** A low scan count combined with `malicious: false` and an older `last_scanned_at` date may lower your confidence that an asset is safe still to use.
### `threat_count`
**Type:** integer · **Returned by:** `check-malicious`, `query-by-username`
The number of verified threats associated with a `resource_identifier` or `username`.
**How to use it:** A value greater than 1 for a resource indicates multiple verified threat records — treat with elevated concern. When using `query-by-username`, a high `threat_count` indicates a prolific malicious publisher and should inform how aggressively you block or monitor other assets from the same account.
### `download_count`
**Type:** integer · **Returned by:** `query-latest`, `threat-feed`
This is a popularity metric indicating the number of times the package has been downloaded from its registry, recorded at the time of detection.
**How to use it:** Use to assess blast radius — a package with millions of downloads that is now flagged as malicious has a much larger potential impact than one with a handful. Use to prioritize response communications and remediation urgency when multiple threats are identified simultaneously.
## Attribution & sourcing
These fields identify who discovered and verified the threat, and link out to corroborating external records.
### `researcher` / `researcher_organization`
**Type:** string · **Returned by:** `query-latest`, `threat-feed`
`researcher` is the OpenSourceMalware username of the person who submitted the threat report. If the threat report was submitted by a team account, it will appear in `researcher_organization`. If both fields are `null`, that indicates the record came directly from the OpenSourceMalware team and bypassed the external submission process.
Users can choose to remain anonymous, so you may not be able to associate the username with a real identity.
**How to use it:** This field is mostly informational but can be used to credit the source of the intelligence. When multiple threats share the same researcher or organization, it may indicate a coordinated research effort or campaign investigation worth following.
### `verified_by`
**Type:** string · **Returned by:** `query-latest`, `threat-feed`
The OpenSourceMalware username of the reviewer who verified the threat report.
**How to use it:** Only use if `researcher` and `researcher_organization` are both `null` as fallback attribution for credit.
### `evidence_references`
**Type:** string · **Returned by:** `query-latest`, `threat-feed`
External evidence supporting the threat report.
**How to use it:** Use to validate the threat record against primary sources. Include in incident reports and leadership briefings as supporting references.
### `osv_advisory_url` / `ghsa_advisory_url`
**Type:** string · **Returned by:** `query-latest`, `threat-feed`
Links to corresponding records in the OSV and GitHub Security Advisory databases, if they exist.
**How to use it:** If you already ingest OSV or GHSA feeds into your vulnerability management tooling, use these links to deduplicate and enrich rather than treating the OSM record as a separate finding. Include in incident reports as corroborating external references.
The absense of an OSV or GHSA record shouldn't be construed as an indicator of a false positive. OpenSourceMalware is a more comprehensive database and often contains threats that haven't yet been issued OSV or GHSA numbers.
### `osm_url`
**Type:** string · **Returned by:** `check-malicious`, `threat-data`
A direct link to the full threat report on opensourcemalware.com.
**How to use it:** Include in analyst alert tickets and incident reports for a one-click pivot to the complete threat record, IOCs, community context, and related campaign information. Reduces time-to-context during triage.
## Response envelope
These fields describe the response itself rather than any individual threat. They are relevant for feed polling and pagination.
### `count`
**Type:** integer · **Returned by:** `query-latest`, `threat-feed`, `query-by-username`
The total number of threat records returned in the response.
**How to use it:** Verify that your ingestion pipeline processed the full result set. Use for pagination planning when building automated ingestion workflows.
### `window_hours` / `from` / `to`
**Type:** integer / timestamp / timestamp · **Returned by:** `threat-feed`
The time window covered by a `threat-feed` response. `window_hours` is the requested lookback period; `from` and `to` are the exact UTC timestamps of the window boundaries.
**How to use it:** After each successful poll, store the `to` timestamp and verify it aligns with the `from` value of your next poll to ensure continuous coverage with no gaps. If your poller goes down, use a larger `hours` value on recovery to backfill missed threats, and confirm the resulting `from` timestamp covers the outage window.