DeepSec: Shield and Spear in One CLI, With a Signed Scope Gate

The two problems DeepSec puts in one binary

AI coding assistants produce a specific class of defect. The README names four: hallucinated packages, hardcoded secrets, unsafe configuration, and what it calls AI pattern errors. A hallucinated package is the sharpest of these, because the import looks ordinary and the failure only appears at install time, or worse, when someone registers the name first. Shield exists to catch that class of mistake before it merges. Spear addresses a different problem: running an authorized penetration test end to end, from reconnaissance through to a proof of concept, without a human driving eight separate tools by hand. The intended user is not a general application developer. It is a security engineer or a red teamer who reviews machine-written code and also runs scoped engagements, and who is willing to learn one command surface for both jobs. The project was renamed from VibeGuard, and the v0.1.5 release is still tagged under that older name, which tells you the platform is a repackaging of an earlier tool rather than a greenfield design.

Shield's three layers and what each one can actually see

Shield runs three detection layers with different mechanisms and different cost. L1 is regex, entropy analysis and a seed catalogue, and the README puts it under 50ms. That combination is what makes hallucinated-package detection possible: a seed catalogue is a local list of known package names, so the check is a lookup, not a network call, and it works offline. The trade-off is that a seed catalogue only knows what someone added to it. L2 uses Tree-sitter WASM to build an AST and looks for SQL injection, XSS, SSRF, path traversal and command injection, quoted at under 2s. AST analysis catches tainted data flow that regex cannot, but it is still static, so anything assembled at runtime through reflection or a dynamic import will not be resolved. L3 is the semantic layer, quoted at under 5s, and it is where the design gets honest about failure: it calls an LLM (DeepSeek, Claude, OpenAI or Ollama) and falls back to local heuristics. The README describes L3 as finding missing authentication, missing rate limiting and missing validation. Those are absences, not patterns, and absence detection is exactly the kind of judgement that varies between runs. Treat L3 output as a review queue, not a pass or fail gate.

Spear's scope gate is the part worth reading twice

Spear automates the sequence Recon, Explore, Fact, Reflect, Report, PoC, and ships 40 or more skill packs wrapping nmap, dirsearch, subfinder, nuclei, sqlmap, ffuf, httpx and feroxbuster. Five roles are documented: pentester, redteam, auditor, blueteam and ctf_player. The mechanism that matters is the authorization check. A target must appear in a whitelist before Spear will run against it, and the README describes three ways to maintain that list: the TUI /scope commands, hand-editing the targets field in ~/.deepsec/targets/scope.json, or signing the file. Signing is optional and gated behind an environment variable, DEEPSEC_SCOPE_SIGNING_KEY, used with deepsec scope sign ./scope.json. The README also states that scope entries are normalized (scheme and host lowercased, trailing slash removed) and deduplicated so that TUI entries match the backend's matching rules. That detail is the difference between a gate and a decoration. If the TUI wrote https://Example.com/ while the engine compared against example.com, every run would fail with an authorization error and users would learn to bypass the check. The README also mentions a time limit and an audit log on signed scope, though it does not specify the default duration, so verify that before an engagement.

Getting it running: pip, cargo, and the no-build path

The README gives three install routes. The Python core and CLI come from pip install -e . run at the repository root. The Rust TUI is optional and built with cargo build --manifest-path tui/Cargo.toml. The IDE plugins are not packaged: the VSCode extension is launched by pressing F5 in the project root to start an Extension Development Host, and the JetBrains plugin is built with cd jetbrains && ./gradlew buildPlugin. There is also a path that requires no compiler at all. GitHub Releases carry deepsec-tui-windows.exe, deepsec-tui-linux and a wheel named deepsec-0.2.0-py3-none-any.whl. The README's three-minute route is to download the Windows executable, double-click it, and type /shield scan on a project. If you want to see output before trusting the tool on your own code, the repository includes demo/unsafe-ai-sample.ts, described as deliberately full of vulnerabilities. Scanning that file first is the cheapest way to learn what the output format looks like. Configuration is unified under ~/.deepsec/config.yaml, which is the one path both the CLI and the TUI read.

TUI commands and the mode switch that blocks Spear

The TUI is a Rust and ratatui application with a three-panel layout: a workspace sidebar, a session log, and a vulnerability inspector. It has a slash-command system with history replay, side-git snapshots for saving and restoring code state, and session persistence bound to Ctrl+S and Ctrl+R. The commands that matter operationally are /scope add, /scope remove and /scope list for the whitelist, /shield scan and /spear run for the two engines, and /report for output. There are three execution modes toggled with Tab: Plan, Agent and YOLO. The README is explicit that Plan mode is read-only and cannot arm Spear, so you must switch to Agent or YOLO first. It also states that YOLO is fully automated with no step-by-step confirmation. That is a deliberate design choice with a real consequence: in YOLO mode the only thing standing between the engine and a target is the scope whitelist. Confirmation at run time is a Y and cancellation is Esc, and Ctrl+C interrupts a run in progress. If your team's process depends on a human approving each step, YOLO is the wrong mode and the README does not offer a middle setting between Agent and full automation.

Where DeepSec is the wrong tool

The clearest limitation is the L1 seed catalogue. Hallucinated-package detection is only as good as the list of names it carries, and the README does not describe how that catalogue is refreshed or whether it can be extended. If your stack depends on internal packages or a private registry, a local seed list of public names will not help, and it may produce noise on names it does not recognize. The second limitation is the L3 layer's dependence on an external provider. It is the only layer that catches missing safeguards, and it needs an API key or a local Ollama instance. On an air-gapped network without Ollama, you lose the layer that finds absences. Third, Spear is gated by a whitelist that must be populated before anything runs. That is correct behaviour, and it also means the tool is useless for opportunistic scanning of an unknown host, which is the point. Finally, the README documents a Windows executable, a Linux binary and a Python wheel, but no macOS artifact, so Mac users should plan on the cargo build or the pip install rather than the download. None of these are defects in the design. They are boundaries you should know before you pick it up.

How it differs from Semgrep and from a standalone pentest framework

Semgrep is the obvious comparison for Shield, and the difference is where the rules come from. Semgrep's core is a pattern language you write yourself against a published rule registry, which means precision is a function of how much rule-writing your team does and the engine stays deterministic. Shield's L1 and L2 are closer to that model, but L3 hands the judgement to an LLM, which trades determinism for coverage of things no pattern expresses, such as a missing rate limiter on a login route. You cannot diff two L3 runs and expect identical output. On the offensive side, compare Spear to a framework like Metasploit, which is a library of exploits you select and configure manually. Spear is the opposite shape: an agent that selects tools from its skill packs and moves through recon to PoC on its own, with the scope whitelist as the guardrail. Metasploit gives an operator precise control and no automation; Spear gives automation and takes control away. The unusual thing about DeepSec is that it ships both halves under one config directory, so a team that audits its own code and also tests its own deployed services does not maintain two toolchains. Whether that combination is worth it depends on whether you need both halves, because each half is thinner than a dedicated tool in its category.

Maintenance, licence and what to check before you commit

DeepSec is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive licence with no copyleft obligation, and it does not carry any warranty, so the accuracy of Shield's findings and the safety of Spear's actions are entirely your responsibility. The MIT grant also says nothing about authorization to test a system; that comes from your engagement contract, not from the scope.json file. On maintenance, the release cadence visible in the material is v0.1.4 and v0.1.5 in July 2026, then v0.2.0 in August 2026, with the last push to main in late August 2026. That is a young project with a fast early cadence, and the version number has not reached 1.0. Expect the CLI surface and the config schema to move. The upgrade cost is concentrated in two places: the ~/.deepsec/config.yaml schema, which both the CLI and the TUI read, and the scope file format under ~/.deepsec/targets/, which the signing step depends on. If you sign scope files, a format change forces a re-sign with DEEPSEC_SCOPE_SIGNING_KEY. Pin the wheel version rather than tracking main if you run Spear against live targets, and re-read the release notes before each bump. The README is available in Chinese with an English translation at README_EN.md, and the quickstart exists in both languages, so the documentation is not a blocker for an English-speaking team.

Editorial conclusion

Adopt DeepSec if you already ship AI-generated code and want a cheap offline first pass (L1 and L2 need no API key) or if you run authorized engagements and want the signed-scope gate and audit log enforced by the tool rather than by a checklist. Do not adopt it if you need a single mature scanner with years of rule tuning, or if your targets cannot be written into scope.json, because Spear will not start without a whitelist entry. Before trusting it, verify three things yourself: that deepsec shield scan ./src on your own repository produces findings you agree with, that the L3 provider you configure is actually reachable (the README shows DEEPSEEK_API_KEY and names DeepSeek, Claude, OpenAI and Ollama), and that the scope normalization in /scope add matches the hostnames your engagement letter covers. The MIT licence gives you the freedom to fork; it does not give you permission to point Spear at anything you were not authorized to test.

Official sources

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