vulners-api-python-sdk

name	vulners-api-python-sdk
description	Use when modifying, testing, documenting, or reviewing the Vulners Python SDK. Covers the v4 architecture (typed sync/async clients, resource namespaces, bulletin model hierarchy, unasync codegen), the preserved legacy v3 surface, uv-based tooling, the 100% branch-coverage gate, safe API-key handling, and defensive vulnerability-intelligence examples.

Vulners API Python SDK skill

Purpose

Maintain the Vulners Python API SDK safely and consistently.

Use this skill for:

• Editing the src/vulners/ package (v4 core or the legacy v3 layer).
• Adding SDK methods for Vulners API endpoints.
• Writing or updating tests under tests/.
• Updating examples in samples/ and documentation under documentation/.
• Reviewing README changes, release automation, and API-key handling.

Do not use this skill for:

• Storing or generating real Vulners API keys.
• Writing exploit weaponization/execution code or operational abuse workflows.
• Moving non-runtime agent instructions into the src/vulners/ package.

Repository context

This skill is consumed from .agents/skills/vulners-api/SKILL.md by Codex-compatible agent harnesses. This repository is the source of truth for the skill.

Current repository layout (src layout, uv_build backend):

api/
├── .agents/skills/vulners-api/   # this skill
├── dev-tools/                    # maintainer tooling (not shipped)
├── documentation/                # mkdocs site source (Material theme)
├── samples/                      # runnable examples: v4/ and legacy/
├── src/vulners/                  # the shipped package
├── tests/                        # pytest suite (core, bc, live, benchmarks)
├── Makefile
├── mkdocs.yml
└── pyproject.toml

Architecture

The primary API is the pair of typed clients in src/vulners/_client.py:

• Vulners (sync) and AsyncVulners (async), re-exported from the package root.
• Resources hang off each client as cached_property namespaces: search, audit, archive, misc, report, stix, subscriptions, subscriptions_v4, webhooks, vscanner (which nests licenses, projects, projects.tasks, projects.results).
• Each resource method declares its endpoint as a module-level RequestSpec (method, path, body mode, unwrap keys, timeout profile, rate-limit group) and routes through one shared request pipeline: credential-safety transport, retries with Retry-After support, and token-bucket rate-limit pacing.
• client.get/post/put/delete are untyped escape hatches for any API path.

Async is the source of truth. The sync mirror is generated:

• Hand-write async code in src/vulners/_resources/_async/ (and _transport_client_async.py, _ratelimit_async.py).
• make unasync regenerates src/vulners/_resources/_sync/ and the sync transport/ratelimit modules via unasyncd (mapping table in [tool.unasyncd] in pyproject.toml). Both sides are committed; make unasync-check gates drift in CI.
• Never hand-edit generated sync files — edit the async source and regenerate.

Bulletin models (src/vulners/_models/) form a base → family → per-collection hierarchy:

• Bulletin — fields common to every document (hand-written, bulletin.py).
• Family models (CveBulletin, ExploitBulletin, …) — one per bulletinFamily, hand-written; construct_bulletin picks the right class.
• Per-collection models — one per collection type, built lazily by the factory in collections.py from generated data in _collections_data.py.
• Field descriptions live once in _field_descriptions.py and flow to models and reference docs. Refresh everything against the live API with python dev-tools/data-models/sample_collections.py (needs an API key).

Legacy v3 surface is preserved for backward compatibility: base.py, vscanner.py, and the src/vulners/vulners/ subpackage keep the old VulnersApi / VScannerApi working unchanged (deprecated — new code should use Vulners / AsyncVulners). The v3 layer is frozen: excluded from strict typing and the coverage gate, guarded by the compatibility oracle in tests/bc/. Do not extend it with new features.

An MCP server (vulners-mcp / python -m vulners.mcp) lives in src/vulners/_mcp/, behind the optional mcp extra (fastmcp).

Adding or changing an endpoint (v4)

1. Pick the resource module in src/vulners/_resources/_async/ by API domain (search.py, audit.py, archive.py, misc.py, report.py, stix.py, subscriptions*.py, webhooks.py, vscanner.py).
2. Declare a module-level RequestSpec for the endpoint and add a typed async method with a Google-style docstring (args, returns, raises).
3. Run make unasync to regenerate the sync mirror.
4. Add tests (mocked HTTP via respx; no live calls) asserting URL, method, body, response parsing, and error paths. The v4 core is held at 100% branch coverage — make cov must stay green.
5. Document the method (the mkdocs reference picks up docstrings; add how-to material under documentation/ if the method is a common task) and add a sample under samples/v4/ if it is commonly used.
6. Regenerate api.md if the public surface changed: python dev-tools/generate_api_md.py.

Backward compatibility: breaking changes only deliberately, documented in release notes / CHANGELOG with the intended versioning impact.

Tooling and quality commands

The project uses uv with PEP 735 dependency groups (uv sync installs the dev toolchain). Python >=3.10; ruff targets py310 — do not use syntax or stdlib APIs unavailable on 3.10. Line length 98.

uv sync                # install project + dev groups
make format            # ruff format + import sorting
make lint              # ruff check + format --check
make typecheck         # mypy + basedpyright
make test              # full pytest suite, parallel (xdist)
make cov               # coverage gate: v4 core at 100% branch coverage
make cov-mcp           # MCP server coverage (isolated env with the mcp extra)
make bc                # backward-compatibility oracle only
make unasync           # regenerate the sync mirror from async sources
make unasync-check     # fail if the committed mirror drifted
make docs              # mkdocs build --strict (any warning fails)
make check             # lint + typecheck + unasync-check + test

uv run pytest tests/<file> runs a single module; make test-fast runs serially for easier debugging.

Testing expectations

Tests live in tests/:

• tests/core/ and top-level tests/test_*.py — the v4 suite: mocked HTTP (respx), request construction, parsing, retries, rate limiting, streaming, secret handling. Deterministic; never require VULNERS_API_KEY.
• tests/bc/ — the backward-compatibility oracle pinning the v3 surface and wire behavior against surface.json / golden files.
• tests/live/ — opt-in live-API tests (marker live); the key comes from the VULNERS_API_KEY env var or the untracked tests/live.local.toml. Skipped by default; keep them minimal and read-only.
• tests/benchmarks/ — pytest-codspeed micro-benchmarks, excluded from the default run.
• tests/test_mcp.py — MCP server tests; run in an isolated env (make cov-mcp) because fastmcp cannot share the default env.

Warnings are errors (filterwarnings = ["error"]): tests that intentionally exercise deprecated shims must opt in locally with pytest.warns(...), never by weakening the global gate.

Security rules

1. Never hardcode API keys, tokens, cookies, or credentials.
2. Use VULNERS_API_KEY from the environment in examples; live tests read it from the environment or tests/live.local.toml (untracked).
3. Mock HTTP responses for unit tests; live tests are opt-in and skipped by default.
4. Do not log API keys or full request headers. The SDK redacts the key in logs, strips it on cross-origin redirects, and keeps it out of reprs — preserve those guarantees when touching transport code.
5. Do not add offensive exploitation workflows; keep examples focused on defensive vulnerability intelligence.
6. Avoid committing real customer data, scan output from private systems, or proprietary asset inventories.

Defensive example categories

Good examples: CVE lookup, bulletin lookup, vulnerability search, software audit, Linux/Windows host audit, SBOM audit, CPE lookup, archive streaming, error handling, pagination and rate-limit handling.

Avoid: exploit weaponization or execution (exploit metadata search is fine), credential harvesting, unapproved scanning of third-party targets, examples that disclose real infrastructure details.

Definition of done

A change is ready when:

• The package imports successfully and make check passes.
• make cov stays at 100% for the v4 core; make unasync-check is clean.
• make docs builds strictly with no warnings.
• No secrets are committed.
• Public SDK methods have docstrings, docs, and (when commonly used) samples.
• Live network tests are opt-in only.
• The v3 compatibility surface is unchanged unless the change is intentionally breaking and documented.