--- name: 1stauthor-osv description: The 1stAuthor osv domain. --- # 1stAuthor OSV 199.7k open-source package security advisories — the part of osv.dev that CVE does not cover. **186.4k are malicious-package reports** (185.7k MAL-*, 177.2k of them npm); the remaining 13.3k are standalone advisories with no CVE id (GHSA / RUSTSEC / PYSEC / GO …). Malicious behaviours (closed set of 13), the legitimate package being impersonated, IOCs (domains / URLs / IPs / filenames, each verified to appear in the advisory text) and one-line summaries are model-extracted. No vectors: structured filters plus bilingual full-text search in Postgres. Base URL `https://api.1stauthor.com`. Every call takes `Authorization: Bearer $FA_API_KEY`; the free samples named below work without a key. Free sample id: `MAL-2026-17452`, free sample query: `malicious npm package`. ## Three verbs, every domain ``` POST /v1/{domain}/search {query, filters?, top_k?} → hits[].id + a card each GET /v1/{domain}/read/{id}?level=brief|detail|full → read as deep as you need POST /v1/{domain}/ask {query, effort: low|medium|high} → an answer with real citations ``` `read` also takes `extra=` for another side of the same document and `format=json|md|html`. At `level=full`, `section=` reads one section and `characters=N` the first N characters. ## Start here - **Poisoned packages in one ecosystem** — `POST /v1/osv/search {"query": "steals environment variables", "filters": {"malicious": true, "ecosystems": "npm"}}` - **Reverse lookup by IOC** — `POST /v1/osv/search {"query": "", "filters": {"indicators": "webhook.site"}}` - **Read one** — `GET /v1/osv/read/MAL-2026-17452` ## Search filters | field | type | meaning | |---|---|---| | `behaviors` | keyword · eq any | Malicious behaviour (closed set of 13, model-assigned): credential_theft / data_exfiltration / downloader_or_dropper / backdoor_or_remote_access / spam_or_token_farming / obfuscated_unknown / other … (several allowed) | | `ecosystems` | keyword · eq any | Package ecosystem: npm 177.2k / PyPI 10.4k / OSS-Fuzz / Linux / Julia / crates.io / Packagist … (several allowed) | | `malicious` | bool · eq | Whether it is a malicious package (186.4k true / 13.3k false) | | `published` | datetime · range | Publication date range | | `source` | keyword · eq any | Advisory source = the id prefix: MAL 185.7k / OSV 4,479 / GHSA 3,786 / UVI 2,337 / JLSEC 1,693 / RUSTSEC 723 / PYSEC 351 | | `vuln_class` | keyword · eq any | Vulnerability class for non-malicious advisories (cve's closed set plus unmaintained) | Rarely needed, but valid: `imitates`, `package_names`, `aliases`, `indicators`. Filters combine with AND; `_or` / `_not` are available. Ranges are `{"gte": n}` / `{"lte": n}`, full text is `{"text": "…"}`. ## Read | level | credits | returns | |---|---|---| | `brief` | 1 | Card: behaviors, doc_id, ecosystems, imitates, malicious, one_liner, one_liner_zh, package_names… | | `detail` (default) | 2 | Every structured field (card plus the source abstract and detail fields) | ## Ask `POST /v1/osv/ask {query, effort}` — Agentic Q&A over this domain: with no vector layer, the model turns the question into structured filters plus bilingual full-text search, reads the hits and answers with [osv: ] citations; /stream is NDJSON with real token deltas. Costs 50 / 100 / 200 credits by effort. Append `/stream` for NDJSON; the first event is always `billing`. `sources` is the retrieval set, not the citation list — filter it by the ids that appear in `answer`. `answer_truncated` means the answer is incomplete; say so. ## Also here ## Facets `GET /v1/osv/facets?field=<field>` lists the legal values for `source`, `vuln_class` — free, no key. Use it instead of guessing a spelling. ## Working rules - **Search first, read second.** A search hit is a card; decide from the card which ids deserve a read. - **Read in layers.** `detail` answers most questions; go to `full` only when the answer is not in it. - **Filters are declared.** An undeclared filter field is a 400, never a silent no-op. `GET /v1/{domain}` lists what exists. - **Cite what you read.** Use the citation format below, and say plainly when the corpus has nothing. - **Failures are not charged.** A 404 costs nothing; an upstream error is refunded. Quote `meta.request_id` when reporting one. Citation format: `[MAL-2026-17452]`. ## What this corpus will and will not tell you - Division of labour with cve: **cve holds CVE-numbered vulnerabilities** (384k from NVD plus KEV and EPSS); **osv holds what CVE does not cover** — overwhelmingly poisoned / impersonating packages (mostly npm), which never get a CVE id. The two domains do not overlap; for supply-chain poisoning, use osv. - Reverse lookup by IOC: filters.indicators=["some-domain"] finds every package that exfiltrates to it. Each IOC was verified to appear in the advisory text — not model-invented. - Typosquatting: filters.imitates is a fuzzy match, so "requests" finds the packages impersonating it. - behaviors and malicious are model-assigned — fine as a summary, not as a quote; the advisory text is details, in level=detail. - ecosystems and package_names are arrays; passing a list means any-match. - Displaying OSV data requires attribution (see the attribution field): the data comes from OSV.dev and its upstream databases, and each advisory's original source (GitHub Advisory / RustSec / PyPA …) keeps its own licence. - **Terms are ANDed** (every term must match), so a long pile of words easily returns nothing — prefer fewer terms plus filters. No vectors: the query runs as an English tsvector and a Chinese zhparser pass whose results are unioned; quoted phrases / OR / -exclusion work. - Model-written fields (summarise, do not quote): behaviors, imitates, impact, indicators, malicious, one_liner, one_liner_zh, vuln_class. - The field table and enumerations are generated from the store's own self-description (search.field), not hand-written; enumeration counts are as of 2026-10-13. --- Generated from https://api.1stauthor.com/v1/osv on 2026-10-14. Full reference: https://1stauthor.com/docs/osv/