Skip to main content
Glama
psirt-exposure
by faithere1

Status: pre-1.0 (alpha) · Cisco IOS XE · 10 reviewed rules · all sample data in this repository is fake. Stack: Python 3.11+ standalone CLI and MCP server, uv, ciscoconfparse2, PSIRT openVuln API, CISA KEV; optional NetBox and Ollama (Foundation-Sec-8B).

Use Case

The Cisco PSIRT openVuln API tells you which software versions an advisory affects and which are fixed. It does not tell you whether the vulnerable feature is enabled on your device. Many advisories only apply when a specific feature is configured (for example ip http server), and Cisco no longer publishes OVAL definitions, so engineers still read every advisory and check every device by hand with show commands.

psirt-exposure automates that check:

  1. Collect: pull advisories from the PSIRT openVuln API and devices from config files or NetBox.

  2. Extract: a security LLM (Cisco Foundation-Sec, run locally) reads the advisory once and turns the "vulnerable only if..." condition into a structured, human-reviewable YAML rule.

  3. Match: a deterministic engine evaluates each rule against each device's version and config. No LLM runs per device.

  4. Report: every device gets one verdict, ranked by active exploitation (CISA KEV):

Verdict

Meaning

AFFECTED

Vulnerable version and the vulnerable feature is enabled

NOT_AFFECTED_FEATURE_DISABLED

Vulnerable version, but the feature is not enabled

FIXED_VERSION

Running a fixed release

MITIGATED

Vulnerable, but the advisory's workaround is applied

INDETERMINATE

Needs runtime data; the exact show command is listed

Each verdict comes with the reason, the config lines it was based on (secrets redacted) and a link to the advisory.

Outcomes: one triage table instead of reading N advisories × M devices, evidence that a reviewer can verify in seconds, KEV-first prioritization, and drift alerts when a config change re-opens an exposure. On the 60-pair golden set the reviewed rules get every verdict right (an upper bound, see Known issues).

Architecture

flowchart LR
    subgraph Sources
        PSIRT["Cisco PSIRT openVuln API<br/>(or local CSAF files)"]
        KEV["CISA KEV catalog"]
        INV["Device configs + show version<br/>(files or NetBox)"]
    end
    subgraph Offline["Once per advisory"]
        LLM["Local LLM<br/>Foundation-Sec-8B (Ollama)"]
        DRAFT["Draft rule (YAML)"]
        REVIEW{"Human review"}
    end
    RULES["rules/*.yaml<br/>status: reviewed"]
    PARSE["IOS XE config parser<br/>(ciscoconfparse2)"]
    MATCH["Deterministic matcher<br/>exposure + mitigations + version"]
    OUT["Verdicts with evidence<br/>CLI table / JSON / Markdown / HTML"]
    MCP["MCP server (stdio)<br/>list_devices, list_rules, check, report"]
    WATCH["watch: drift vs. last run"]

    PSIRT -- advisory text --> LLM --> DRAFT --> REVIEW --> RULES
    PSIRT -- affected versions --> MATCH
    KEV -- exploited CVEs --> MATCH
    INV --> PARSE --> MATCH
    RULES --> MATCH
    MATCH --> OUT
    MATCH --> MCP
    MATCH --> WATCH

The LLM only turns advisory text into a rule, once, and a human reviews the rule before check uses it. Per-device matching has no LLM in the loop: the same inputs always give the same verdicts. Configs never leave the host; in live mode only software versions are sent to Cisco.

Related MCP server: network-mcp-server

Installation

Requirements: Python 3.11+, git and uv. uv installs a suitable Python if you do not have one. No account or API key is needed for offline mode.

Install uv:

# macOS
brew install uv                                     # or the Linux command below
# Linux and macOS
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Clone and install:

git clone https://github.com/faithere1/psirt-exposure
cd psirt-exposure
uv sync
uv run psirt-exposure --help

Tested on macOS; CI runs on Linux (Ubuntu). Windows should work with the same uv commands but is not tested yet.

Configuration

Offline mode needs no configuration. For live data, copy the template and fill in only what you use (.env is gitignored; never put credentials anywhere else):

cp .env.example .env        # Windows: copy .env.example .env

Variable

Needed for

Format

CISCO_CLIENT_ID, CISCO_CLIENT_SECRET

live advisory/version data (check without --offline)

Client credentials of a free Cisco API Console app with the PSIRT openVuln API

NETBOX_URL

--netbox

Base URL with scheme, no /api suffix, e.g. http://127.0.0.1:8000

NETBOX_TOKEN

--netbox

NetBox API token: v1 (40 hex chars) or v2 (nbt_<key>.<secret>)

OPENAI_API_KEY

extract --backend openai only

API key of your OpenAI-compatible server; set it in the shell environment (extract does not read .env)

NETBOX_DB_PASSWORD, ...

local NetBox lab only

Generated by uv run python -m psirt_exposure.netbox.secrets >> .env

Device data in file mode is one directory per device:

<configs-dir>/<hostname>/running-config.txt   # output of "show running-config" (required)
<configs-dir>/<hostname>/show-version.txt     # output of "show version" (recommended: PID + version)

Without show-version.txt the version and PID are unknown: a disabled feature still gives NOT_AFFECTED_FEATURE_DISABLED, but an enabled one (or a rule that needs the platform) gives INDETERMINATE. Point --configs at your own directory; keep real configs outside this repository.

Usage

Check devices (offline)

uv run psirt-exposure check --offline --evidence                # all sample devices x all rules
uv run psirt-exposure check --offline --device edge-rtr-01 --format json
uv run psirt-exposure check --offline --configs ~/my-configs --rule webui --rule snmp

Offline mode reads rules/ and samples/configs/<hostname>/{running-config,show-version}.txt. Version status comes from the local CSAF files in tests/fixtures/psirt/ (--advisories DIR): a version listed as known_affected for "Cisco IOS XE Software" is affected; an unlisted version is fixed if its release train is listed or newer than every listed train; an older, unlisted train (Cisco does not evaluate releases past end of maintenance) is INDETERMINATE. Secrets (SNMP communities, passwords, keys) are redacted in the evidence lines.

Live mode (openVuln + CISA KEV)

cp .env.example .env        # then fill in CISCO_CLIENT_ID / CISCO_CLIENT_SECRET
uv run psirt-exposure check --evidence

Without --offline, check asks the PSIRT openVuln API (OAuth2 client credentials from a Cisco API Console app) which advisories affect each device's IOS XE version, one request per distinct version, and flags rule CVEs that are in the CISA KEV catalog (KEV column). Mix sources with --versions openvuln|csaf|none and --kev cisa|none|FILE. Only software versions are sent to Cisco; configs never leave the host.

Live smoke tests are opt-in: PSIRT_EXPOSURE_LIVE=1 uv run pytest -m live.

NetBox inventory

check --netbox reads devices from NetBox instead of --configs: the device type's part number (or model) is the PID, and two custom fields on devices hold the data that show version and the config files provide in file mode: software_version (text) and running_config (long text). Set NETBOX_URL and NETBOX_TOKEN in .env; v1 (Token) and v2 (nbt_…, Bearer) tokens both work. Narrow the device query with --netbox-filter KEY=VALUE (any NetBox device filter, repeatable).

A local lab with the sample devices (needs Docker and Compose, e.g. brew install colima docker docker-compose && colima start). The Homebrew package provides the docker-compose command used below; with Docker Desktop, write docker compose instead.

uv run python -m psirt_exposure.netbox.secrets >> .env   # random lab passwords + API token
docker-compose --env-file .env -f netbox/docker-compose.yml up -d --wait
uv run psirt-exposure netbox-seed                         # idempotent
uv run psirt-exposure check --offline --netbox --netbox-filter site=psirt-lab
docker-compose --env-file .env -f netbox/docker-compose.yml down -v   # stop the lab and delete its data

NetBox runs on http://127.0.0.1:8000 (user admin, password NETBOX_SUPERUSER_PASSWORD). The compose file is a trimmed copy of netbox-docker; --offline still allows --netbox, because it only concerns advisory and KEV sources.

Reports

uv run psirt-exposure check --offline --format markdown --output report.md
uv run psirt-exposure check --offline --format html --output report.html

A report has a verdict summary, a per-device table and one section per AFFECTED, INDETERMINATE or MITIGATED result: the advisory link and CVEs, CISA KEV dates, the reason, the redacted evidence lines, the show commands that confirm runtime facts, and the fix. Besides "upgrade to a fixed release", rules can carry IOS XE config snippets: mitigations[].snippet applies the advisory's workaround, remediation.snippet removes the exposure (for example no vstack or no ip http server). <name> marks a value to fill in. The HTML file is self-contained (no scripts, no external assets).

MCP server

psirt-exposure mcp runs a Model Context Protocol server over stdio (official mcp Python SDK), so an AI assistant can ask "which of my devices are affected?" and get deterministic verdicts with evidence.

Tool

Purpose

list_devices

Inventory devices with PID and version (inventory: files or netbox)

list_rules

Reviewed rules: advisory, CVEs, title, exposure summary

check

One verdict per device and rule, with reason, evidence, runtime checks, KEV

report

The Markdown or HTML report described above

Resource template psirt-exposure://rules/{rule_id} returns a rule as YAML. Tools accept device and rule names, never file paths; the directories are fixed at start-up (--configs, --rules, --advisories, --env-file). Defaults are offline (versions="csaf", kev="none"); a client must ask for versions="openvuln", kev="cisa" or inventory="netbox" explicitly.

Client configuration (Claude Desktop, Claude Code .mcp.json, Cursor, ...):

{
  "mcpServers": {
    "psirt-exposure": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/psirt-exposure", "psirt-exposure", "mcp"]
    }
  }
}

Try it with MCP Inspector:

npx @modelcontextprotocol/inspector uv run --directory "$PWD" psirt-exposure mcp
npx @modelcontextprotocol/inspector --cli uv run --directory "$PWD" psirt-exposure mcp \
  --method tools/call --tool-name check --tool-arg only_findings=true

Drift watch

watch re-runs check (same source options) and compares the result with the snapshot of the previous run, so new exposure from a config change, a new device, updated advisory or version data, or a new KEV listing shows up as a change:

uv run psirt-exposure watch --offline                     # first run saves the baseline
uv run psirt-exposure watch --offline                     # later runs print the changes
uv run psirt-exposure watch --interval 3600 --count 24    # hourly for a day (live sources)

The snapshot lives in .psirt-exposure/watch-state.json (--state, gitignored) and holds only verdicts, exposure, mitigation ids, KEV CVEs and redacted evidence text (no line numbers, so an unrelated edit higher up in a config is not reported). Change kinds: new, gone, verdict, evidence, kev. --format json prints machine-readable changes. Exit code: 0 no drift, 1 drift in any run (for cron or CI), 2 setup or state-file error.

Draft rules with an LLM

psirt-exposure extract turns advisory text into a draft rule. The model reply is constrained by the rule JSON Schema and then validated like a hand-written rule; invalid replies are retried with the validation error. Advisory IDs, CVEs and titles are copied from the advisory, never generated.

Default backend: Foundation-Sec-8B-Instruct on a local Ollama (advisories stay on the host).

ollama pull hf.co/fdtn-ai/Foundation-Sec-1.1-8B-Instruct-Q4_K_M-GGUF
ollama create foundation-sec-8b-instruct -f ollama/foundation-sec-8b-instruct.Modelfile
uv run psirt-exposure extract                           # all fixture advisories -> eval/<model>/rules/
uv run psirt-exposure eval-extraction --drafts eval/ollama-foundation-sec-8b-instruct/rules

The Modelfile adds the chat template that the published GGUF lacks; without it the system prompt is dropped. Any OpenAI-compatible server works too (key read from OPENAI_API_KEY):

uv run psirt-exposure extract --backend openai --model <name> --base-url http://localhost:8000/v1

Drafts are written under eval/, not rules/, so check ignores them until a human reviews one, sets status: reviewed and moves it into rules/. eval-extraction runs drafts and hand rules through the same matcher on the sample devices and writes report.md / report.json next to the drafts.

Evaluation

uv run psirt-exposure eval-golden scores final verdicts on 60 held-out advisory×config pairs (eval/golden/); see eval/README.md for the metrics table and caveats.

Try psirt-exposure on a real IOS XE device with a free DevNet Sandbox, for example an always-on or reservable IOS XE (Catalyst 8000V) or a Cisco Modeling Labs sandbox:

  1. Connect to the device over SSH with the credentials shown on the sandbox page.

  2. Run terminal length 0, then show running-config and show version.

  3. Save the outputs as ~/psirt-lab/<hostname>/running-config.txt and ~/psirt-lab/<hostname>/show-version.txt (outside this repository).

  4. Run uv run psirt-exposure check --offline --configs ~/psirt-lab --evidence, or drop --offline to use live openVuln data.

psirt-exposure only reads the saved text; it never logs in to the device. Sandbox configs contain real addresses and shared credentials, so do not commit them or paste them into issues.

Known issues

  • Cisco IOS XE only; NX-OS and ASA are not supported yet (the parser and rule interfaces are kept platform-agnostic).

  • Only advisories with a rule in rules/ get a config-level verdict (10 today). Other openVuln advisories for a device's version are not reported yet.

  • Some facts cannot be read from a config (active L2TP tunnels, UDP 500 reachable, IOx running); those results are INDETERMINATE and list the show command to run.

  • The golden labels were written by the rule author, so the 60/60 score in eval/README.md is an upper bound. Independent labels are very welcome.

  • LLM drafts from Foundation-Sec-8B are not good enough to use unreviewed (see the eval report); that is why every rule needs status: reviewed.

  • No client-side throttling for the openVuln API yet; keep long watch --interval runs modest.

  • psirt-exposure never logs in to devices. Treat its output as triage, not a guarantee; confirm with Cisco's advisory and the Cisco Software Checker.

Bugs and wrong verdicts are tracked in GitHub Issues; use the issue templates and attach a minimal fake config, never a real one.

Getting help

  • Questions, wrong verdicts and feature requests: open a GitHub issue.

  • Security problems in psirt-exposure: follow SECURITY.md (private reporting, not a public issue).

Getting involved

The most useful contributions right now:

  • New rules for feature-dependent IOS XE advisories (one YAML file plus tests).

  • Independent golden labels: devices and expected verdicts written by someone other than the rule author.

  • NX-OS and ASA support, openVuln client-side throttling, reporting advisories that have no rule.

CONTRIBUTING.md explains the rule workflow and the no-real-data rules. All participants follow the Code of Conduct.

Development checks (the same as CI):

uv sync
uv run ruff check . && uv run ruff format --check . && uv run mypy && uv run pytest
uv run --with pillow python scripts/demo_gif.py          # regenerate docs/demo.gif

Credits and references

Licensing info

Copyright 2026 faithere1. Licensed under the Apache License 2.0; see LICENSE and NOTICE (third-party attributions).

psirt-exposure is not affiliated with or endorsed by Cisco Systems, Inc.

Available Tools

4 tools
checkA
Read-onlyIdempotent

Match advisory rules against device configs; one verdict per device and rule.

Verdicts: AFFECTED, NOT_AFFECTED_FEATURE_DISABLED, FIXED_VERSION, MITIGATED, INDETERMINATE. Each item has the reason, redacted evidence lines, runtime checks to run on the device and CISA KEV entries. devices / rules: names from list_devices / list_rules (default: all). versions: "csaf" (local CSAF files, offline), "openvuln" (live Cisco API) or "none". kev: "none" or "cisa" (download the CISA KEV feed). only_findings: keep only AFFECTED, INDETERMINATE and MITIGATED items.

Inputs: kev, rules, devices, versions, +3 more. Returns: result

list_devicesA
Read-onlyIdempotent

List inventory devices with platform (PID) and IOS XE version.

inventory: "files" (sample config directory) or "netbox". netbox_filter: NetBox device query parameters, e.g. {"site": "psirt-lab"}.

Inputs: inventory, netbox_filter. Returns: result

list_rulesA
Read-onlyIdempotent

List the reviewed advisory rules: id, advisory, CVEs, title and exposure summary.

Inputs: no named parameters. Returns: result

reportB
Read-onlyIdempotent

Render a Markdown or HTML report: summary, per-device counts, and findings with evidence and mitigation / remediation config snippets. Arguments as for check.

Inputs: kev, rules, format, devices, +3 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct role: listing advisory rules, listing inventory devices, matching rules to configs, and rendering a report. The check/report pair share arguments, but their outputs and purposes are clearly separated.

    Naming Consistency4/5

    Names are all lowercase snake_case and readable, with list_rules/list_devices following a verb_noun pattern. check and report are bare verbs, which is a minor deviation but not confusing.

    Tool Count5/5

    Four tools are well-scoped for a PSIRT exposure workflow: discover rules, discover devices, analyze exposure, and report findings. Each tool earns its place without redundancy.

    Completeness4/5

    The surface covers the core lifecycle from inventory and advisory listing through assessment and reporting. Minor gaps exist, such as no standalone advisory-detail or runtime-check execution tool, but these are not critical for the stated purpose.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to interact with Cisco IOS-XE network devices over SSH using structured tools. Provides read and write capabilities for network management with built-in validation and security.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for network operations that lets AI assistants interact with Cisco/Juniper network devices through safe, well-defined tools like compliance audits and configuration backups.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for Cisco Catalyst SD-WAN Manager (vManage) that exposes REST API as tools for AI assistants to query and manage SD-WAN fabric, including device management, monitoring, templates, and policies.
      9
      MIT