Metadata-Version: 2.4
Name: pyapicheck
Version: 0.8.0
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Security
License-File: LICENSE
Summary: Discover APIs from an OpenAPI spec, classify sensitive fields, and score risk — with every score traceable to a named reason, not a black-box number.
License-Expression: Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# PyAPICheck

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

[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

> **Not to be confused with [PyNetworkIntel](https://github.com/Mullassery/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](https://github.com/Mullassery/PyDeepMesh) |
| Understand *why* a Python dependency exists, who added it, and whether it is actually used | [PyDependencyCheck](https://github.com/Mullassery/PyDependencyCheck) |
| Statically analyze a **dbt** project (risky tests, test blast radius, cost) | [PyDBTGuard](https://github.com/Mullassery/PyDBTGuard) |
| Statically analyze **Apache Beam / Dataflow** pipelines (cost, hot keys, reliability) | [PyBeamGuard](https://github.com/Mullassery/PyBeamGuard) |
| Validate **Airflow** DAGs and dbt runs | [PyAirflowTester](https://github.com/Mullassery/PyAirflowTester) |
| Simulate cascading-failure **blast radius** across infrastructure, data pipelines, and AI systems | [PyBlastRadius](https://github.com/Mullassery/PyBlastRadius) |
| Check the **quality of the data itself** at runtime (schema, drift, anomalies) | [StatGuardian](https://github.com/Mullassery/StatGuardian) |
| Discover **devices, services, and vulnerabilities on a network** | [PyNetworkIntel](https://github.com/Mullassery/PyNetworkIntel) |
| Discover and score **API security** risk (real traffic, agent/MCP, Cedar policy) | [PyAPICheck](https://github.com/Mullassery/PyAPICheck) |
| Trace and root-cause **AI agent** failures | [PyAgentHound](https://github.com/Mullassery/PyAgentHound) |
| Diagnose **RAG retrieval** failures | [PyVectorHound](https://github.com/Mullassery/PyVectorHound) |
| Orchestrate **local, dependency-aware tasks** (DAG scheduler + content-addressed cache) | [PyTaskWireCheck](https://github.com/Mullassery/PyTaskWireCheck) |

[Browse all projects →](https://github.com/Mullassery?tab=repositories)

## 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.

```bash
pip install pyapicheck
```

From source (development):

```bash
maturin develop
```

## Quick start

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

```bash
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).

## Usage

- **Discover API surface** (single file or entire repo):
  ```bash
  pyapicheck discover openapi.yaml
  pyapicheck discover ./services/
  ```

- **Gate on regressions in CI**:
  ```bash
  pyapicheck discover openapi.yaml --fail-on-high
  ```

- **Detect drift between revisions**:
  ```bash
  pyapicheck diff old.yaml new.yaml
  ```

- **Cross-reference with access logs (zombie/shadow detection)**:
  ```bash
  pyapicheck report openapi.yaml access.log
  ```

- **Build/inspect agent security graph from MCP config** (requires a Postgres+AGE `--db-url`):
  ```bash
  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):
  ```bash
  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**:
  ```bash
  pyapicheck remediate openapi.yaml --json > plan.json
  ```

For all subcommands and flags, run:

```bash
pyapicheck --help
```

## SARIF / GitHub code scanning

```bash
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](CHANGELOG.md) — Version history and release notes.
- [CONTRIBUTING.md](CONTRIBUTING.md) — Development setup, testing, and contribution guidelines.
- [ROADMAP.md](ROADMAP.md) — Phase-by-phase plan and what's done vs. deferred.
- [ROADMAP_HONEST.md](ROADMAP_HONEST.md) — Honest assessment of maturity, gaps, and technical debt.
- [SECURITY.md](SECURITY.md) — Vulnerability reporting.

## Contributing

Contributions are welcome. Please read [CONTRIBUTING.md](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](LICENSE).

