deep-scan

What it is

deep-scan (kubeek-sec/deep-scan) is a Python 3.13 uv workspace. Beyond the architecture the summary already covers, the page gives the concrete entry points for actually standing it up and evaluating it — install order, scan invocations, a CI gate, a bundled vulnerable test target, and a one-command full-stack deploy.

How it works

All front-ends (CLI, MCP, REST/web app, kruncher fleet) share one engine, one normalized Finding model, (location, message) deduplication, and four report formats: JSON, Markdown, HTML, SARIF 2.1.0. Scans auto-detect static (directory) vs. dynamic (running URL). Reports land in reports/scan_<timestamp>_<mode>/report.{json,md,html,sarif}.

What to do

Install, then fetch pinned checksum-verified tools (this step is required before scanning):

uv sync
uv run deepscan tools install all

Scan a directory or a running URL; run the offline AI-free taint engine alone; or use as a CI gate:

uv run deepscan scan ./my-project
uv run deepscan scan http://127.0.0.1:3000
uv run deepscan scan ./my-project --scanner analysis
uv run deepscan scan ./my-project --fail-on high

--fail-on high exits 1 on a HIGH+ finding. A deliberately-vulnerable project with ground-truth findings ships for validation:

uv run deepscan scan ./guinea-pig

Bring up the whole stack (Postgres, kruncher, REST/web, MCP, ASPM), scaling workers to 4:

cp deploy/docker/.env.example deploy/docker/.env
docker compose -f deploy/docker/docker-compose.yml up --build --scale kruncher=4

(or ./start.sh). Then: web/REST http://127.0.0.1:8800/, ASPM http://127.0.0.1:8900/, MCP http://127.0.0.1:8000/mcp. To verify the sandboxing end-to-end without a real cluster, ./k8s-test.sh spins up an ephemeral kind cluster.

Preconditions / Affected

Full sandbox hardening (non-root, read-only rootfs, all capabilities dropped, RuntimeDefault seccomp, no service-account token, default-deny egress, optional gVisor runsc) is described as Kubernetes behavior, requiring a gvisor RuntimeClass pinned to a tainted sandbox node pool. The isolated dependency-resolution container needs an internal package mirror to restrict egress to. Docker Compose gets you the stack but not this Kubernetes hardening.

Caveats

The code-graph engine (taint, reachability, choke points) is explicitly labeled work-in-progress ("wip") on the page. AI triage is optional and read-only. The page repeatedly stresses that scanning untrusted repos is inherently dangerous — dependency resolution runs arbitrary package-manager code — so the hardening is a mitigation you must enable and verify (per docs/sandboxing.md), not a default of the simple uv run path.