DeepSec Review: Shield Code Auditing and Spear Pentest Automation in One CLI

The gap DeepSec aims at: AI-written code that passes review

Most static analysis tools were designed for code a human typed. DeepSec targets a narrower failure class: code an assistant generated. The README lists the L1 layer as catching hallucinated packages, hardcoded secrets, unsafe configuration and what it calls AI error patterns, using regex, entropy analysis and a seed catalog. That is a real problem. A model can import a package that does not exist, and a reviewer skimming a diff will not check every import against a registry. The second audience is red teams. Spear is described as an end-to-end automated penetration engine migrated from a project called VulnClaw, with 40+ built-in skill packs (nmap, dirsearch, subfinder, nuclei, sqlmap, ffuf, httpx, feroxbuster) and five roles: pentester, redteam, auditor, blueteam, ctf_player. Both halves share one config root at ~/.deepsec/config.yaml, one CLI named deepsec, and one Rust TUI. If you only need linting, that bundling is overhead. If you are the person who both reviews the AI pull request and gets asked to test the deployed service, the shared config is the point.

How Shield's three detection layers divide the work

Shield runs three layers with different mechanisms and different time budgets, and the split matters when you decide what to run in CI. L1 is documented as regex plus entropy analysis plus a seed catalog, under 50ms, and it is the layer that catches hallucinated packages and hardcoded secrets. L2 uses Tree-sitter WASM AST analysis and is quoted at under 2s for SQL injection, XSS, SSRF, path traversal and command injection. L3 is the semantic layer, under 5s, aimed at missing authentication, missing rate limiting and missing validation, and it calls an LLM (DeepSeek, Claude, OpenAI or Ollama) with a local heuristic fallback. The design is sensible: cheap deterministic checks run first and offline, and the expensive probabilistic layer is opt-in. The trade-off is that L3's quality is whatever the configured model gives you, and the fallback is described only as heuristic, so a fully offline run gets you L1 and L2 and nothing semantic. Note also that the layer timings are the project's own figures; they are not independent measurements, and they will move with repository size and hardware.

Installing DeepSec and running a first Shield scan

The README gives two paths. The source path installs the Python core and CLI in editable mode from the repository root, which is what you want if you intend to modify the detectors. The no-compile path is a Release download: deepsec-tui-windows.exe, deepsec-tui-linux, or the wheel deepsec-0.2.0-py3-none-any.whl. The Python requirement is 3.10 or newer per pyproject.toml.

pip install -e .

That installs the deepsec and deepsec-tui entry points defined under [project.scripts]. The Rust TUI is optional and built separately:

cargo build --manifest-path tui/Cargo.toml

The first real use is a scan of a directory. The README's own example points at ./src, and the default run is offline:

deepsec shield scan ./src

You should expect findings from L1 and L2 only, since L3 needs a key. To turn on semantic analysis, the README shows the key being passed inline:

DEEPSEEK_API_KEY=... deepsec shield scan ./src --layer l3

For CI, the same command can emit SARIF, which most code-scanning dashboards ingest:

deepsec shield scan . --format sarif --output deepsec.sarif

The repository ships demo/unsafe-ai-sample.ts, a file the README says is deliberately full of vulnerabilities. Scanning that file first is the cheapest way to confirm the install works and to see what the detectors actually report before you point them at your own tree.

Spear's signed scope: the authorization model is the product

Spear will not run against an arbitrary host. Targets must be in an authorization whitelist, and the README offers two ways to maintain it: manually editing the targets field in ~/.deepsec/targets/scope.json, or the TUI's /scope add command. The TUI path normalizes the target (scheme and host lowercased, trailing slash removed) and deduplicates, which the README says matches the backend's authorization matching rules. If you want cryptographic enforcement, the README documents exporting DEEPSEC_SCOPE_SIGNING_KEY and running deepsec scope sign ./scope.json, described as strong signature verification, with time limits and audit logs alongside it. The run command takes the scope file explicitly:

deepsec spear run https://authorized-target.example --authorized ./scope.json

There is a recon-only variant, deepsec spear recon, and two inspection commands, deepsec spear roles and deepsec spear tools --role pentester. This is the most defensible part of the project: an automated pentest engine that refuses to touch anything outside a declared scope is easier to justify to a client than one that takes a bare URL. The limitation is that a scope file is only as good as the person who wrote it. Nothing in the README describes a check that the person signing the scope owns the target.

The TUI, its modes, and the Plan-mode trap

The terminal workbench is Rust plus ratatui, with a three-panel layout (workspace sidebar, session log, findings inspector), a slash-command system, Side-Git snapshots for creating and restoring code state, and session persistence on Ctrl+S and Ctrl+R. Execution modes are Plan, Agent and YOLO, toggled with Tab. One detail is worth reading twice: the README states that Plan mode is read-only and cannot arm Spear directly, so you must switch to Agent or YOLO before a run. That is a deliberate safety interlock, and it is also a usability trap for anyone who starts the TUI, types a spear command in Plan mode, and sees nothing happen. YOLO is described as fully automatic with no step-by-step confirmation. For a pentest engine that can execute sqlmap and nuclei, an unconfirmed mode is a decision you should make consciously rather than by pressing Tab until something runs. The README also notes Ctrl+C during a run, but the excerpt ends there, so the exact interruption semantics are not documented in the available description.

Where DeepSec is the wrong tool

Three cases stand out. First, if you need a single-purpose SAST tool with years of rule tuning and a stable rule-authoring format, DeepSec is a young bundle: pyproject.toml classifies it as Development Status 3 - Alpha, and the release history starts at v0.1.4 in July 2026. Second, if your environment cannot send code to an external model, you lose L3 entirely and are left with the regex, entropy and AST layers. The README names Ollama as an option, which keeps inference local, but the local heuristic fallback is not described in any detail, so treat it as a safety net rather than a substitute. Third, if you want to run an unattended pentest against production, the scope model is a hard boundary, not a suggestion: targets outside the whitelist will not be touched. That is the correct behavior, but it means DeepSec cannot be dropped into a workflow where someone expects to point it at a URL and get results. The README also does not document rollback for anything Shield fixes or Spear changes, so treat any apply-fix command as one-way until you verify otherwise.

DeepSec against Semgrep, and the licence position

The closest widely used alternative is Semgrep, and the difference is architectural rather than cosmetic. Semgrep is a pattern-matching engine driven by rules you write or import, with no LLM layer and no pentest component; it is deterministic, auditable and easy to pin in CI. DeepSec replaces rule authoring with a fixed three-layer pipeline and adds an optional model call for semantic findings, plus a separate offensive engine in the same binary. If your team already maintains Semgrep rules, DeepSec will not replace that investment, and the L3 layer's findings will be harder to reproduce run to run than a rule match. If your problem is specifically hallucinated imports and secrets in AI-generated code, DeepSec's L1 is aimed at exactly that and Semgrep has no equivalent concept out of the box. On licensing, DeepSec is MIT, and the wheel metadata in pyproject.toml declares license = { text = "MIT" }. That is permissive and imposes no copyleft on your own code. It says nothing about the licences of the external tools Spear invokes (nmap, nuclei, sqlmap and the rest), which you should check separately before bundling them into a commercial engagement, and nothing about the terms of whichever LLM provider you configure for L3. This is not legal advice; read the LICENSE file and the third-party tool licences yourself.

Maintenance, releases and upgrade cost

The repository is not archived, and the last push was on 2026-08-24, so it is currently being worked on. The release cadence visible in the project's history is short: v0.1.4 and v0.1.5 both landed on 2026-07-13, and v0.2.0 on 2026-08-12. That pace is a real upgrade cost, because the project has already renamed itself once, from VibeGuard to DeepSec, and v0.1.5 still carries the VibeGuard tag. Anything you pin today should be pinned by version, not by branch. The config root ~/.deepsec/ is shared by Shield, Spear and the TUI, so a change to the scope file format or the config schema affects all three at once; the repository does include an "Upgrade documentation.md" file at the top level, which is the place to check before moving versions. For containerized use, the Dockerfile builds the Rust TUI in a rust:1-bookworm stage and the Python package in python:3.12-slim, with HOME and DEEPSEC_HOME both set to /data and a named volume mounted there, so scope files and config survive a container restart. docker-compose.yml runs the image with command: ["tui"], which means the default container behavior is the interactive workbench, not a one-shot scan.

Editorial conclusion

Adopt DeepSec if you already ship AI-generated code and want an offline L1/L2 pass plus an optional LLM layer in the same CLI you would use for an authorized pentest. Skip it if you need a mature, narrowly scoped SAST product with a long support history: pyproject.toml still classifies the package as Development Status 3 - Alpha, and the README does not document rollback for Shield fixes or Spear runs. Before trusting it in CI, run the bundled demo/unsafe-ai-sample.ts through deepsec shield scan so you can see exactly which findings the L1 and L2 layers produce on your own tree.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. Unclecheng-li/DeepSec on GitHub