# Vigía · API guide for agents

Base: `https://vigia.tribi.es/api/v1` · Full schema: `https://vigia.tribi.es/api/v1/openapi.json`

Authentication: `Authorization: Bearer vg_…`. Tokens are created in the web UI
(Settings → API tokens) or with `POST /api/v1/tokens`, and carry scopes:

| scope | what for |
|---|---|
| `read` | read findings, projects, inventory, channels and status |
| `write` | the above + act on findings, create projects, upload inventory |
| `admin` | everything, including channels, settings and tokens |
| `inventory:write` | only upload inventory (best bound to a project) |
| `check` | only the CI gate |

## Concepts

- **Project**: something you deploy (`my-app`). It has `internet_exposed`, which
  raises critical issues to urgent.
- **Source**: one list of components of a project (`app`, `binaries`…). Every
  upload **fully replaces** the previous one for that source; whatever
  disappears closes its findings by itself ("fixed").
- **Finding**: an advisory that affects a component deployed in a project.
  States: `new` → `acknowledged` → `resolved` (automatic when the fix is
  deployed). Others: `not_affected` (with a VEX justification), `risk_accepted`
  (until a date, then it reopens), `withdrawn` (the source retracted it).
- **Priority**: `urgent` (malware, KEV, or critical in something exposed; always
  alerts, also at night, and repeats until acknowledged), `high` (alerts at once
  outside quiet hours), `normal` (daily digest), `low` (web only). Every finding
  has `reasons`: why it has that priority.

## Recipes

What needs attention now:

    GET /api/v1/findings?state=new&priority=urgent,high

One finding with its history, fixed versions and references:

    GET /api/v1/findings/{id}

Act on it (all accept `note`):

    POST /api/v1/findings/{id}/ack
    POST /api/v1/findings/{id}/not_affected   {"justification": "vulnerable_code_not_in_execute_path", "note": "…"}
    POST /api/v1/findings/{id}/accept         {"until": "2026-12-31", "note": "…"}
    POST /api/v1/findings/{id}/reopen
    POST /api/v1/findings/{id}/comment        {"note": "PR #123 fixes it"}
    POST /api/v1/findings/{id}/resolve        {"note": "…"}   (only if nothing will be redeployed)

Justifications: `component_not_present`, `vulnerable_code_not_present`,
`vulnerable_code_not_in_execute_path`,
`vulnerable_code_cannot_be_controlled_by_adversary`,
`inline_mitigations_already_exist`.

Where do I use a package?

    GET /api/v1/components?name=lodash

Upload an inventory (the body is the file as is):

    curl -fsS -H "Authorization: Bearer $T" --data-binary @package-lock.json \
      "https://vigia.tribi.es/api/v1/inventory?project=my-app&source=app&ref=$(git rev-parse --short=12 HEAD)"

Formats: package-lock (npm), yarn.lock, pnpm-lock.yaml, CycloneDX JSON, SPDX
JSON, requirements.txt, Pipfile.lock, poetry.lock, uv.lock, Cargo.lock, go.mod,
composer.lock, Gemfile.lock, Go binaries, dpkg status, apk installed, and our own:

    {"components": [{"ecosystem": "npm", "name": "next", "version": "16.0.7", "scope": "runtime", "direct": true}]}

Check a lockfile without storing it (the CI gate). Returns 422 if something
blocks:

    curl -sS --fail-with-body -H "Authorization: Bearer $T" --data-binary @package-lock.json \
      "https://vigia.tribi.es/api/v1/check?block=malicious&format=github"

What happened since you last looked:

    GET /api/v1/events?since=2026-11-14T08:00:00Z

Vigía's own health (Uptime Kuma can watch `/readyz` too):

    GET /api/v1/status

Channels (secrets can be written but are never returned):

    POST /api/v1/channels {"kind": "telegram", "name": "Phone", "min_priority": "high",
                           "config": {"chat_id": "-100…"}, "secrets": {"bot_token": "…"}}
    POST /api/v1/channels/{id}/test

Settings: `GET/PATCH /api/v1/settings` (`timezone`, `quiet_hours`, `digest_time`,
`reminder_hours`, `epss_threshold`, `intervals`, `github_token`).

## Good practice for agents

- Before acknowledging or dismissing, read `GET /findings/{id}`: `reasons`,
  `recommended_fix`, `presence` (which source and since when) and `references`.
- `not_affected` requires a justification and leaves a trail; use it only with
  evidence.
- Fixed issues close by themselves when the new inventory arrives: no need to
  `resolve` if the fix gets deployed.
- To ask about a specific CVE: `GET /api/v1/vulnerabilities/CVE-…?fetch=true`.