api-threat-model

Turn an OpenAPI spec into a security analysis in under 30 seconds. Point it at a spec file or URL — it produces a STRIDE threat model, prioritized test plan, and flagged endpoints for IDOR, auth bypass, mass assignment, and injection.

No API keys. No AI. No internet needed (except for remote specs). Pure heuristic classification from real pentest methodology.

---

Setup

Step 1: Check Python Version

python3 --version
# Must be 3.10 or higher. If not, upgrade at python.org

Step 2: Create Virtual Environment

# Create venv
python3 -m venv .venv

# Activate it
source .venv/bin/activate       # macOS / Linux
# .venv\Scripts\activate        # Windows

Step 3: Install

# Clone the repo
git clone https://github.com/SanaullahAmanullah/api-threat-model.git
cd api-threat-model

# Install with pip
pip install .

Step 4: Verify Installation

api-threat-model --version
# Expected: api-threat-model v0.1.0

api-threat-model --help
# Shows available commands: scan, classify, endpoints

---

Usage

Step 5: Run Your First Scan

# Full analysis against the included test spec
api-threat-model scan tests/sample-spec.json

# Against a remote OpenAPI spec
api-threat-model scan https://petstore.swagger.io/v2/swagger.json

# Output to custom directory
api-threat-model scan openapi.yaml --output ./my-reports

What happens:

  Loading spec: tests/sample-spec.json
  API: Vulnerable E-Commerce API v1.0.0
  Endpoints found: 7
  Classifying endpoints...
  Flagged: 6/7 (Critical: 3, High: 4, Med: 1, Low: 0)
  Generating STRIDE threat model...
  Threats identified: 29

  Report saved to: ./findings/
  - api-security-analysis-2026-08-10.md
  - api-test-plan-2026-08-10.md

  Done.

Step 6: Read the Output

Open the generated reports:

ls findings/
# api-security-analysis-2026-08-10.md   — Full STRIDE model + endpoint inventory
# api-test-plan-2026-08-10.md           — Prioritized test cases in order

The analysis report contains:

1. Executive Summary — counts by severity
2. Flagged Endpoints — sorted by risk (Critical → Low), with test suggestions
3. Complete Endpoint Inventory — every endpoint with auth status and risk
4. STRIDE Threat Model — per-endpoint threat analysis
5. Testing Priority Queue — ordered test cases

Step 7: Other Commands

# Classification only (faster, no threat model)
api-threat-model classify tests/sample-spec.json

# Just list endpoints (no analysis)
api-threat-model endpoints tests/sample-spec.json

# Read from stdin (pipe)
cat openapi.json | api-threat-model scan -

---

What the Tool Catches

Vuln Class	Heuristic	Confidence
IDOR (Read)	GET with object ID in path/params + auth required	Medium
IDOR (Write)	POST/PUT/DELETE with object ID + auth	Medium
Missing Auth	Write operation with no security requirements	High
Mass Assignment	Request body has role/permission/privileged fields	Medium
Injection	Search/filter endpoint accepting raw user strings	Low
Destructive Op	DELETE without explicit admin scope	Low

Flag confidence is labeled on every finding. High = the spec explicitly shows the issue. Low = interesting surface characteristic, needs manual review.

---

Troubleshooting

Problem	Fix
api-threat-model: command not found	Make sure venv is activated. Run pip install -e . for dev mode
No module named 'yaml'	Run pip install pyyaml
No 'paths' found in spec	The file isn't a valid OpenAPI spec. Check it has paths: at the top level
YAML error on spec load	Run python3 -c "import yaml; yaml.safe_load(open('your-spec.yaml'))" to test
Remote URL fails	The spec URL must be publicly accessible. For authenticated URLs, download first: curl -H "Authorization: Bearer ..." URL > spec.json
Python < 3.10	Upgrade Python or use Docker: docker run -v $(pwd):/data python:3.12 pip install api-threat-model && api-threat-model scan /data/spec.json

---

Architecture

api-threat-model/
├── api_threat_model/
│   ├── cli.py              # argparse: scan, classify, endpoints
│   ├── parser.py            # OpenAPI JSON/YAML loader (file, URL, inline)
│   ├── classifier.py        # Heuristic classification engine (IDOR, auth, injection, etc.)
│   ├── threat_model.py      # STRIDE per-endpoint generator
│   └── reporter.py          # Markdown report + test plan generator
├── tests/
│   └── sample-spec.json     # Deliberately vulnerable 7-endpoint test spec
├── pyproject.toml
└── README.md

Author

Sanaullah Amanullah — @SanaullahAmanullah
Application Security Consultant | OSCP | Synack Red Team

License

MIT