Metadata-Version: 2.4
Name: paranoid-cli
Version: 1.6.0
Summary: Open-source iterative threat modeling powered by LLMs - STRIDE + MAESTRO frameworks with DREAD scoring
Author: Astitva
Maintainer: Astitva
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/theAstiv/paranoid
Project-URL: Repository, https://github.com/theAstiv/paranoid
Project-URL: Documentation, https://github.com/theAstiv/paranoid#readme
Project-URL: Changelog, https://github.com/theAstiv/paranoid/blob/main/CHANGELOG.md
Project-URL: Issue Tracker, https://github.com/theAstiv/paranoid/issues
Keywords: threat-modeling,security,stride,maestro,llm,ai,security-analysis,dread,risk-assessment,cybersecurity,appsec,devsecops
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Environment :: Console
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn[standard]>=0.32.0
Requires-Dist: anthropic>=0.42.0
Requires-Dist: openai>=1.58.1
Requires-Dist: httpx>=0.28.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: pydantic-settings>=2.10.0
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: sqlite-vec>=0.1.6
Requires-Dist: fastembed>=0.4.2
Requires-Dist: reportlab>=4.2.5
Requires-Dist: python-multipart>=0.0.19
Requires-Dist: mcp>=1.3.1
Requires-Dist: Pillow>=10.0.0
Requires-Dist: aiofiles>=24.1.0
Requires-Dist: click>=8.1.7
Requires-Dist: cryptography>=42.0
Requires-Dist: argon2-cffi>=23.1.0
Requires-Dist: PyJWT>=2.10.0
Provides-Extra: dev
Requires-Dist: pytest>=8.3.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.25.0; extra == "dev"
Requires-Dist: pytest-cov>=6.0.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.3.1; extra == "dev"
Requires-Dist: ruff>=0.8.4; extra == "dev"
Requires-Dist: httpx>=0.28.0; extra == "dev"
Requires-Dist: pypdf>=5.0.0; extra == "dev"
Provides-Extra: bedrock
Requires-Dist: boto3>=1.35.0; extra == "bedrock"
Provides-Extra: build
Requires-Dist: build>=1.2.0; extra == "build"
Requires-Dist: twine>=6.0.0; extra == "build"
Requires-Dist: pyinstaller>=6.11.0; extra == "build"
Dynamic: license-file

# Paranoid

**Open-source, self-hosted, iterative threat modeling powered by LLMs.**

Paranoid takes system descriptions (text, diagrams, or code via MCP) and produces comprehensive STRIDE + MAESTRO threat models through an LLM-powered pipeline with deterministic fallback. Configure 1–15 automated iteration passes, then review threats in a human-in-the-loop approve/reject cycle.

## Features

- **Zero Infrastructure**: SQLite + sqlite-vec. One command: `docker compose up`
- **Multi-Provider LLM**: Anthropic, OpenAI, Ollama (fully local/air-gapped), or AWS Bedrock
- **Dependency Capability Engine**: static-analysis visibility into what an npm dependency can do (network, filesystem, process, dynamic code, native addons), diffed against its own GitHub source — see [below](#dependency-capability-engine)
- **Dual Framework**: STRIDE (traditional) + MAESTRO (AI/ML) — auto-detected or run in parallel
- **DREAD + CVSS Risk Scoring**: automatic 5-dimension DREAD (0–10) and/or a standalone CVSS v3.1 base-score calculator, selectable per run
- **ATT&CK / ATLAS Enrichment**: every threat — LLM-generated, rule-engine, or dependency — is mapped to MITRE ATT&CK/ATLAS techniques (deterministic rule table, pattern-ID regex, or embedding similarity depending on origin), never self-attributed by the LLM
- **Iterative Refinement**: 1–15 configurable iteration passes with gap analysis
- **Model Routing**: per-pipeline-step fast/main model selection (e.g. Haiku for extraction, Sonnet for threat generation); the routed extraction steps cost about two-thirds less ([measured](docs/benchmarks.md#2-model-routing)), and the steps that write the threat text never leave the main model
- **Code-as-Input**: Semantic code extraction via context-link MCP (`--code /path/to/repo`)
- **Image-as-Input**: Multiple architecture diagrams per run — up to 5 named views (deployment, data flow, etc.) via a repeatable `-d` on the CLI (`-d arch.png -d flow.mmd`) or the API's `diagrams[]` field, rendered with a proper ELK layout
- **Deterministic Rule Engine**: 362 curated patterns (STRIDE, MAESTRO, OWASP, MITRE ATT&CK/ATLAS, CAPEC, cloud misconfigs) across 16 seed files
- **Export Formats**: JSON, SARIF (GitHub Security), Markdown, PDF
- **Multi-User Collaboration**: Projects with owner/editor/viewer RBAC, threaded comments, assignments, activity log
- **CI/CD Ready**: CLI + GitHub Action with SARIF upload

## Quick Start

```bash
# Install
pip install paranoid-cli

# Configure
paranoid config init

# Run (the examples are in the repo, not the package: clone it, or fetch one)
curl -fsSLO https://raw.githubusercontent.com/theAstiv/paranoid/main/examples/stride-example-api-gateway.md
paranoid run stride-example-api-gateway.md   # saved to the database; add -o threats.json for a file
```

**Docker (web UI + API):**
```bash
git clone https://github.com/theAstiv/paranoid && cd paranoid
cp .env.example .env        # add your API key
mkdir -p data               # must be writable by uid 1000: `sudo chown 1000:1000 data` if yours differs
docker compose up --build   # web UI at http://localhost:8000/app
```

> **Note:** the dependency capability engine, Bedrock, model routing, multiple diagrams, CVSS and ATT&CK/ATLAS mapping need v1.6.0 or later (`pip install "paranoid-cli>=1.6.0"`). The dependency engine also needs [Semgrep](https://semgrep.dev) on `PATH` (`pip install semgrep`); the Docker image includes it.

## Try the full demo (Black Hat India Arsenal 2026)

[`examples/arsenal-deps/`](examples/arsenal-deps/) is "MediaDrop", a fictional image-upload service with 8 real npm dependencies and three diagrams of the same system. Every command below runs against it.

```bash
# 1. Dependency capabilities inside a threat model (heatmap + drift in the web UI)
paranoid run examples/arsenal-deps/description.md \
  --manifest examples/arsenal-deps/package.json \
  --lockfile examples/arsenal-deps/package-lock.json --deps-source both

#    A reconstructed (inert) event-stream-style incident: capability delta + drift, no LLM call
python examples/arsenal-deps/inject_incident.py --source both --no-llm

# 2. Three diagrams, ATT&CK/ATLAS techniques, CVSS next to DREAD
paranoid run examples/arsenal-deps/description.md -n 2 \
  -d examples/arsenal-deps/diagrams/architecture.mmd \
  -d examples/arsenal-deps/diagrams/upload-flow.mmd \
  -d examples/arsenal-deps/diagrams/deployment.png \
  --step-model extract_assets=main --step-model extract_flows=main \
  --scoring-method both

# 3. Iterations + model routing, SARIF for GitHub code scanning
paranoid run examples/arsenal-deps/description.md -n 3 -v \
  --manifest examples/arsenal-deps/package.json \
  --lockfile examples/arsenal-deps/package-lock.json \
  --format sarif -o mediadrop.sarif
```

CLI runs are saved to the local database (`paranoid models list`); start the web UI against the same `DB_PATH` to open them at `http://localhost:8000/app`. Set `ANTHROPIC_EFFORT=medium` for Claude: at the default effort a run takes about three times as long. Measured costs, timings and their sample sizes are in [Benchmarks](docs/benchmarks.md).

**What the dependency engine claims:** capability visibility plus change and discrepancy triage: what a dependency can do, what changed in a release, and what ships in the npm tarball that isn't in the repo. It doesn't claim to catch supply-chain attacks; see [what it does not catch](#dependency-capability-engine).

## Documentation

| Guide | Description |
|-------|-------------|
| [Getting Started](docs/getting-started.md) | Install, configure, and run your first threat model |
| [CLI Reference](docs/cli-reference.md) | All flags, subcommands, and output formats |
| [Configuration](docs/configuration.md) | All environment variables and config options |
| [Web UI Guide](docs/web-ui-guide.md) | Browser interface walkthrough |
| [Authentication](docs/authentication.md) | Multi-user setup, JWT, PATs, RBAC |
| [API Reference](docs/api-reference.md) | REST API — 83 route handlers across 13 route modules, plus `/health` and `/` in `main.py` |
| [GitHub Action](docs/github-action.md) | Automated threat modeling in CI/CD |
| [Architecture](docs/architecture.md) | System design, pipeline, data model |
| [Benchmarks](docs/benchmarks.md) | An 11-model comparison on AWS Bedrock, routing savings per step, multi-diagram extraction, iterations, wall time, reliability and dependency-engine gates — dated, with sample sizes and caveats |
| [Deployment](docs/deployment.md) | Docker, PyPI, binary, production hardening |

**Other docs:**
- [CHANGELOG.md](CHANGELOG.md) — Release history
- [CONTRIBUTING.md](CONTRIBUTING.md) — How to contribute
- [SECURITY.md](SECURITY.md) — Vulnerability reporting policy
- [TESTING.md](TESTING.md) — Testing and CI guide
- [Input-template.md](Input-template.md) — Structured input template reference
- [examples/](examples/) — Working STRIDE and MAESTRO examples

## Dependency capability engine

Static-analysis visibility into what an npm dependency can actually *do* —
network access, filesystem, process spawning, dynamic code, native addons,
and more — compared against its declared GitHub source, so a version bump
that quietly adds a capability shows up before you install it.

```bash
# What can this package do? Fetches npm tarball + GitHub source, runs Semgrep.
paranoid deps scan chalk@5.3.0 --source both

# Did capabilities change between two versions? (this is the *shape* of
# checks that would have caught the real ua-parser-js/event-stream
# supply-chain compromises: a patch release quietly adding a capability
# nothing in the diff would obviously explain. These two specific versions
# are both clean — the actual malicious 0.7.29 was unpublished — this just
# shows the delta computing cleanly against real registry data.)
paranoid deps diff ua-parser-js 0.7.28 0.7.30 --source both

# Sweep every direct dependency in your project's package.json
paranoid deps scan-manifest path/to/your-project/package.json
```

Requires [Semgrep](https://semgrep.dev) on `PATH` (`pip install semgrep`) —
see `SEMGREP_BINARY`, `DEPS_CACHE_DIR`, `DEPS_MAX_TARBALL_MB` in
[Configuration](docs/configuration.md#dependency-capability-engine). Source is
always fetched read-only; nothing scanned is ever executed or installed.

**What `deps scan` reports:** a `CapabilityProfile` per source — categories
(`network`, `filesystem`, `process`, `dynamic_code`, `native_ffi`,
`persistence`, `authentication`, `environment`, `crypto`, `deserialization`,
`build_install`), each backed by file:line evidence and a real source
snippet, plus any `postinstall`/`preinstall` lifecycle hooks.

**What drift signals mean:** with `--source both`, `paranoid deps scan`
compares the npm tarball against the package's own GitHub source for *one*
version, per file. `paranoid deps diff` is a separate comparison — did this
package's capabilities change between two releases — computed from two
tarball scans; with `--source both` it *additionally* reports drift for the
newer version alone, using the same per-file logic described here:

- **matched / explained_by_sourcemap / explained_by_build** — the tarball
  file's capabilities are all accounted for by the corresponding GitHub file,
  a valid source map, or a declared build step. No signal.
- **relocated** (weak, informational) — a capability new to *that* file but
  already present elsewhere in the package. Worth a look, not proof of
  anything.
- **signal** (strong) — a capability novel to the *entire* GitHub-side scan.
  This is the actionable finding: shipped code does something the published
  source doesn't explain anywhere.
- **generated_unverifiable** (informational) — a file declared by the
  package's own **GitHub** manifest (never the tarball's — the tarball is
  attacker-controlled, so trusting its self-declaration would let an
  attacker excuse any file just by listing it) that a non-npm build
  toolchain (e.g. esbuild's Go build, `cargo build.rs`) produces outside of
  `npm run build`. Can't be verified against source either way; never
  contributes a strong signal.
- **unverifiable** — the tarball file's GitHub counterpart couldn't be
  fetched (a skipped symlink, an over-long path). Excused only against the
  package-wide GitHub category set, so a genuinely novel category still
  signals.
- Added `postinstall`/`preinstall` hooks are graded separately: a
  non-allowlisted addition is a strong signal on its own (the
  `ua-parser-js`-shaped compromise, caught without needing a previous
  version to diff against).

**What it does not catch:**

- **Runtime-fetched payloads.** A package that `fetch()`s and `eval()`s a
  remote payload at runtime shows up as a `network`/`dynamic_code`
  capability — the engine flags that the capability exists, not what the
  fetched code will do.
- **Obfuscation beyond the flagged shapes.** The scanner recognizes specific,
  deliberate evasion patterns (aliased `require`/`Function`, concatenated or
  computed property calls, low-level `process.binding`, etc. — see
  `backend/deps/rules/js/dynamic_code.yaml`), not every possible way to hide
  a call. A sufficiently determined, hand-crafted obfuscation can still slip
  past static analysis; this is capability visibility and drift triage, not
  a guarantee of detection.
- **Generated files with no declared build step**, or generated outside a
  recognized non-npm toolchain marker, still count as ordinary shipped code
  and can trip a signal even when they're legitimately build output.
- **Non-JS/TS package ecosystems.** Layer 1 is npm/JS+TS only; PyPI and
  other ecosystems aren't covered yet.

Read this as "here's what changed and what looks unexplained," not
"this dependency is safe" or "this dependency is malicious" — every signal
is meant to be triaged by a person, not acted on automatically.

## Supported platforms

| Platform | PyPI | Docker | Binary |
|----------|------|--------|--------|
| Ubuntu 20.04+ | ✓ | ✓ | ✓¹ |
| macOS 11+ ARM64 | ✓ | ✓ | ✓ |
| Windows 10+ | ✓ | ✓ | ✓ |
| WSL2 | ✓ | ✓ | ✓¹ |

¹ From v1.6.0 (`paranoid-linux-x64`). The v1.5.0 release has no Linux binary: its macOS build overwrote it, as both were named `paranoid`.

Full platform matrix: [docs/deployment.md](docs/deployment.md)

## Development Status

**v1.6.0** — dependency capability engine, multi-user collaboration (accounts, projects, roles), AWS Bedrock, per-step model routing, multiple diagrams with ELK rendering, ATT&CK/ATLAS mapping and CVSS v3.1 scoring. See the [CHANGELOG](CHANGELOG.md).

**v1.5.0** — Non-technical users can open the web app, paste an API key, link a Git repo, and get a threat model — no terminal required.

**Future:** OIDC/SSO federation.

## License

Apache 2.0
