PyAPICheck

Every API risk score traces back to a named, checkable reason—never a black-box number.

Not to be confused with PyNetworkIntel: PyNetworkIntel discovers network hosts/services; PyAPICheck scores API security risk (real traffic, agent/MCP, Cedar policy).

Which project do I need?

Part of the Mullassery open-source family. These tools have similar names — here is the short version of who does what:

If you need to…	Use
Build a repository's dependency graph and match it against vulnerability advisories (Python, Rust, Node, containers)	PyDeepMesh
Understand why a Python dependency exists, who added it, and whether it is actually used	PyDependencyCheck
Statically analyze a dbt project (risky tests, test blast radius, cost)	PyDBTGuard
Statically analyze Apache Beam / Dataflow pipelines (cost, hot keys, reliability)	PyBeamGuard
Validate Airflow DAGs and dbt runs	PyAirflowTester
Simulate cascading-failure blast radius across infrastructure, data pipelines, and AI systems	PyBlastRadius
Check the quality of the data itself at runtime (schema, drift, anomalies)	StatGuardian
Discover devices, services, and vulnerabilities on a network	PyNetworkIntel
Discover and score API security risk (real traffic, agent/MCP, Cedar policy)	PyAPICheck
Trace and root-cause AI agent failures	PyAgentHound
Diagnose RAG retrieval failures	PyVectorHound
Orchestrate local, dependency-aware tasks (DAG scheduler + content-addressed cache)	PyTaskWireCheck

Browse all projects →

What it is

PyAPICheck analyzes OpenAPI specifications and cross-references them with real gateway traffic to detect API security issues with full traceability. Unlike generic vulnerability scanners that return opaque severity scores, PyAPICheck produces concrete findings that cite the exact factors causing each risk, enabling teams to verify and act on them with confidence.

Built with a Rust core and Python bindings (via PyO3), PyAPICheck focuses on business-logic authorization gaps—like endpoints that should require authentication but don't, missing security schemes, or inconsistent authorization across operations. It also supports security graph modeling for AI agents/MCP tools, behavioral baselining, and Cedar policy generation.

Features / Highlights

• Evidence-backed findings: Every risk factor includes a named severity and description explaining exactly why the finding exists.
• Spec discovery: Scan single OpenAPI specs, entire directories/monorepos, or Postman collections to inventory API surface.
• Drift detection: Compare spec revisions to catch newly added, removed, or changed endpoints before they ship.
• Observed vs. declared analysis: Cross-reference specs with access logs to identify zombie (declared but unused) and shadow (observed but undeclared) endpoints.
• MCP/agent security graph: Build a graph of agents, tools, and resources from live MCP configurations to analyze reachability and blast radius.
• Behavioral baselining: Detect BOLA-shaped access patterns and first-time operations per identity based on real traffic.
• Cedar policy generation: Recommend, validate, and diff Cedar authorization policies with findings backed by concrete evidence.
• Automated remediation: Generate machine-readable remediation plans for OpenAPI specs.
• Traceable by design: All findings maintain full provenance back to the specific spec locations and traffic evidence that produced them.

Who it's for / Use cases

• Security reviews: Evaluate OpenAPI specs before shipping, whether for a single service or across an entire monorepo.
• CI/CD gating: Fail builds on high/critical findings or on API security regressions detected via spec diffing.
• API lifecycle management: Identify unused ("zombie") endpoints or undocumented ("shadow") endpoints by reconciling with production traffic.
• AI agent governance: Model MCP servers and agents to understand what they can reach, assess blast radius if compromised, and generate enforceable Cedar policies.
• Authorization hardening: Catch missing authentication, inconsistent security requirements, and overly permissive endpoint exposure.

What it is not

• Not a generic web vulnerability scanner: PyAPICheck focuses on authorization and API surface correctness, not broad classes like XSS, SQLi, or server misconfiguration exploits. Tools like ZAP and pyapicheck are complementary.
• Not a live enforcement engine: It generates Cedar policies and an Envoy configuration artifact, but does not wire or deploy them to gateways. Deployment remains a manual step.
• Not production-hardened as an enforcement control plane yet: The system is advisory/artifact-oriented for many workflows (see Project status).
• Not LLM-powered out of the box: Sensitive field classification uses a lightweight keyword heuristic (designed to be swappable for models like Presidio); the AI Security Analyst (Phase 5) is not implemented at this time.

Project status

• Core functionality (Phases 0-4, 6-7): Discovery, diffing, traffic reconciliation, graph modeling, behavioral baselining, Cedar policy operations, and Envoy artifact emission are implemented and covered by tests.
• AI Security Analyst (Phase 5): Not started. This is explicitly deferred pending citation-verifiable findings.
• Maturity: Advisory-first. Artifacts are designed to be validated and reviewed by humans before deployment. Envoy configs should be validated in a staging environment before production use.

Installation

PyAPICheck is distributed as a Python package via PyPI and includes Rust-compiled extensions. Requires Python ≥ 3.9.

pip install pyapicheck

From source (development):

maturin develop

Quick start

Analyze an OpenAPI spec and view risk findings with traceable reasons:

pyapicheck discover openapi.yaml

Output includes each endpoint, risk level and score, the exact risk factors (each with severity), and any sensitive fields identified (with location: query/path/body/header).

OpenAPI linting (vacuum / Spectral)

Lint the contract itself with vacuum (MIT) or Spectral (Apache-2.0):

brew install vacuum                     # Go binary (quobix/vacuum)
npm install -g @stoplight/spectral-cli  # Node CLI

pyapicheck lint openapi.yaml --tool auto --fail-on-findings
pyapicheck lint openapi.yaml --json

The adapter uses whichever binary is installed, parses JSON findings when the tool provides them, and reports missing linters explicitly.

Active testing (Schemathesis)

Static discovery tells you which operations look risky. Active testing proves it by generating property-based and stateful tests from the same OpenAPI schema:

pip install "pyapicheck[active]"

pyapicheck active openapi.yaml --url http://127.0.0.1:8000 \
  --checks all --phases coverage,fuzzing --max-time 60 --fail-on-failure

The adapter invokes the MIT-licensed Schemathesis CLI, parses its JSON report and prints failures/errors. --json returns the structured summary. Network errors, missing binaries, and non-zero exits are surfaced honestly; a failed run is never reported as a pass.

Usage

• Discover API surface (single file or entire repo):

  pyapicheck discover openapi.yaml
  pyapicheck discover ./services/
  

• Gate on regressions in CI:

  pyapicheck discover openapi.yaml --fail-on-high
  

• Detect drift between revisions:

  pyapicheck diff old.yaml new.yaml
  

• Cross-reference with access logs (zombie/shadow detection):

  pyapicheck report openapi.yaml access.log
  

• Build/inspect agent security graph from MCP config (requires a Postgres+AGE --db-url):

  pyapicheck graph load-mcp mcp.json --db-url postgresql://user:pass@host/db
  pyapicheck graph reachable <agent_name> --db-url postgresql://user:pass@host/db
  pyapicheck graph blast-radius <resource_name> --db-url postgresql://user:pass@host/db
  

• Behavioral baselining and Cedar policies (baseline and recommend each take a historical and a current access log):

  pyapicheck baseline openapi.yaml historical.log current.log --json > baseline.json
  pyapicheck policies recommend openapi.yaml historical.log current.log > policy.cedar
  pyapicheck policies validate policy.cedar
  pyapicheck policies emit-envoy policy.cedar --out envoy.yaml
  

• Generate remediation plan:

  pyapicheck remediate openapi.yaml --json > plan.json
  

For all subcommands and flags, run:

pyapicheck --help

SARIF / GitHub code scanning

pyapicheck discover openapi.yaml --sarif > pyapicheck.sarif

Upload the result with github/codeql-action/upload-sarif. One SARIF result is emitted per named risk factor (no opaque endpoint-level result), with the source spec as the artifact location.

Documentation

• CHANGELOG.md — Version history and release notes.
• CONTRIBUTING.md — Development setup, testing, and contribution guidelines.
• ROADMAP.md — Phase-by-phase plan and what's done vs. deferred.
• ROADMAP_HONEST.md — Honest assessment of maturity, gaps, and technical debt.
• SECURITY.md — Vulnerability reporting.

Known issues and deferred work

Blocked / failed:

• Live traffic connectors and Presidio PII; Linux/Windows wheels.

Rejected / deferred:

• DAST parity or live enforcement.

Full shipped/blocked/rejected detail: QUEUE_STATUS.md.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before submitting changes. CI runs Rust tests/clippy/fmt, builds the Python extension via maturin, runs the Python test suite, and performs a cargo audit dependency vulnerability check.

License

This project is licensed under the Apache License 2.0.