# deepsec: An Agent-Powered Vulnerability Scanner for Large Codebases

> deepsec is a Vercel Labs tool that uses coding agents to find hard-to-find security vulnerabilities in large, existing codebases. Scans can cost thousands of dollars for big repositories, but the tool resumes automatically from where it left off if interrupted.

**vercel-labs/deepsec** — GitHub describes it as Deepsec is a security harness for finding vulnerabilities in your codebase powered by coding agents. The repository metadata lists TypeScript as its primary language. The metadata lists the Apache-2.0 license. This article stays within the project description and details documented in the GitHub repository README.

- Repository: https://github.com/vercel-labs/deepsec
- Website: https://deepsec.sh/
- Stars: 7,986 · Forks: 485
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-08-13 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/vercel-labs-deepsec

## What deepsec Is and the Problem It Targets

deepsec is an agent-powered vulnerability scanner from Vercel Labs, designed to surface security issues that have been present in a codebase for a long time and have not been caught by routine code review or simpler automated tools. The README describes its goal as finding issues that would otherwise go unfixed, with the expectation that teams will patch them quickly once found.

The tool is configured for on-demand use rather than continuous monitoring. It is intended for large-scale existing repositories where an exhaustive security review would take significant time manually. The README is explicit about cost: scans use models at maximum thinking levels and can reach thousands or even tens of thousands of dollars for large codebases. Vercel's own customers are cited as having found the cost worth it for the speed at which they were able to close long-standing vulnerabilities.

deepsec targets security engineers and engineering teams who need a periodic deep audit. It is not a substitute for a pattern-based linter running on every pull request; the README documents a separate PR-mode workflow (process --diff) for scanning only changed files in a diff.

## How the Scan Pipeline Works

deepsec operates in a pipeline of discrete commands. The first step is scan, which uses regex matchers to find candidate sites in the codebase quickly and for free without calling any AI model. The second step is process, where an AI agent investigates each candidate in depth and emits findings with a remediation recommendation. The optional third step is revalidate, which re-checks existing findings and also checks git history to see whether a flagged issue has already been fixed in a later commit.

The README's workflow table lists additional commands: triage for a lightweight classification of findings into priority levels (P0, P1, P2) using a cheaper model, enrich for adding git committer information and optional ownership data, report for generating a Markdown and JSON summary, and export for producing per-finding JSON or a directory of Markdown files for sharing with the team.

All state lives in a .deepsec/ directory created at the root of the scanned repository. If a run is interrupted for any reason, whether by a Ctrl-C, a network issue, or a spending limit, re-running the same command picks up where it left off. Files already analyzed in a previous run are skipped. This resume behavior applies to both single-machine and distributed runs.

For large codebases, work fans out across Vercel Sandbox microVMs in parallel using the sandbox subcommand, distributing the agent workload across multiple isolated environments.

## Running Your First deepsec Scan

deepsec requires Node 22 or newer. From the root of the repository you want to scan, run:

```bash
npx deepsec init
```

This command guides through picking an AI model (with benchmark scores and prices shown for comparison), choosing how to pay for model usage (Vercel AI Gateway or a direct API key), and then runs unattended: it studies the codebase, scans it, and performs the AI review. The only addition to your repository is a .deepsec/ directory.

To cap spending and run time before starting:

```bash
npx deepsec init --max-cost-usd 100 --max-duration 2h
```

When the initial scan finishes, export the findings as a directory of Markdown files:

```bash
cd .deepsec
pnpm deepsec export --format md-dir --out ./findings
```

For subsequent scans on the same codebase, work from inside .deepsec/ using the individual pipeline commands:

```bash
pnpm deepsec scan        # fast pattern scan, free
pnpm deepsec process     # AI review of new candidates
pnpm deepsec revalidate  # optional, cuts false-positive rate
pnpm deepsec export --format md-dir --out ./findings
```

After initialization, agents and tools can read documentation matching the installed CLI at .deepsec/node_modules/deepsec/SKILL.md.

## Distributed Execution and PR-Mode Scanning

For large monorepos, the sandbox subcommand fans work across Vercel Sandbox microVMs in parallel. The local working tree is tarballed and uploaded to the microVMs; the .git directory is excluded. Model credentials remain on the host machine and are injected only at the selected egress point:

```bash
pnpm deepsec sandbox process --project-id my-app --sandboxes 10 --concurrency 4
```

The sandboxing also has a security benefit described in the README: API keys for the coding agents are injected outside the sandbox and cannot be exfiltrated from within it. Worker sandbox network egress is limited to coding agent hosts during the scan phase.

For teams who want to gate pull requests, deepsec supports process --diff, which restricts the AI review to files changed in a specified diff. The README points to a separate reviewing-changes documentation file for the full CI workflow. This is significantly cheaper than a full scan, though it only covers new code rather than existing vulnerabilities.

The .env.example shows the two environment variables used for the Claude Agent SDK backend: ANTHROPIC_AUTH_TOKEN and ANTHROPIC_BASE_URL, defaulting to the Vercel AI Gateway at https://ai-gateway.vercel.sh. Running with your own Anthropic API key involves setting ANTHROPIC_AUTH_TOKEN to your key and pointing ANTHROPIC_BASE_URL to the Anthropic endpoint directly.

## Cost, Security Exposure, and Limitations

The README is unusually direct about cost: scans can reach tens of thousands of dollars for large codebases when using maximum thinking levels on the most capable models. The --max-cost-usd flag is the practical control; setting it prevents runaway spending on a first run.

The README treats deepsec like a coding agent with full shell access on the machine where it runs. The advice is to run it on trusted inputs. Prompt injection through external dependencies or vendored code is a risk the README acknowledges: third-party code in your repository can contain strings designed to influence the agent's analysis. Using the sandbox option limits this exposure.

deepsec does not store your API key directly; it stores the name of the environment variable holding the key. However, the agent has read access to all the code it scans, and the AI model receives that code as input. Teams with strict data handling requirements should review how the chosen AI provider handles code submitted for analysis.

The tool requires your codebase to contain recognizable patterns for the regex matchers to find candidates. The scan command's coverage depends on the built-in matchers and any custom matchers you write; the README documents a separate writing-matchers guide for extending coverage to project-specific patterns.

## Comparing deepsec to Pattern-Based Static Analysis

Semgrep is a widely used pattern-based static analysis tool for security. It runs locally, finishes in seconds on most codebases, and is free for many use cases. Its model is explicit rules written by engineers: a rule describes a specific code pattern (an unsafe deserialization call, a SQL string concatenation, an unvalidated redirect) and Semgrep finds all instances matching that pattern.

deepsec works differently. Instead of matching patterns, it sends the code to a coding agent that reasons about the code's behavior and infers potential vulnerabilities without requiring a pre-written rule for each one. This is slower and more expensive, but it can surface issues that do not have explicit rules: logic errors, authorization gaps, or interactions between components that only become dangerous in combination.

The two tools are complementary rather than mutually exclusive. Semgrep runs continuously in CI and catches known bad patterns on every commit. deepsec runs periodically as a deep audit to find what Semgrep misses. The README explicitly positions deepsec as an on-demand tool rather than a CI gate, and its separate --diff mode is the narrower option for PR-level review.

## License, Maintenance, and AI Provider Options

The repository is licensed under Apache-2.0, an open license that allows commercial use, modification, and distribution, with patent and trademark clauses. The last push to the repository was on 2026-09-16.

By default, deepsec routes all model calls through Vercel AI Gateway, which provides access to multiple AI models without needing provider-specific API keys. The gateway is listed in the README as providing access to every major model. Running without a Vercel account requires passing --model-auth direct with --ai-provider and --ai-api-key-env to the init command; this mode works with OpenAI, Anthropic, or a custom HTTPS endpoint.

When a process or revalidate run halts because a provider credential runs out of quota, deepsec stops and reports where to add credits. Re-running the same command afterward resumes from the last checkpoint. This behavior applies to both the Vercel AI Gateway path and direct provider keys.

## Conclusion

deepsec is designed for a specific situation: a team that wants a thorough, one-time or infrequent deep security audit of an existing large codebase and is willing to pay significant API costs for completeness. It is not a replacement for frequent, lightweight pattern scans in CI. Before running a full scan, cap the cost and duration with --max-cost-usd and --max-duration, and decide whether to route through Vercel AI Gateway or bring your own API key. Read .deepsec/node_modules/deepsec/SKILL.md after initialization for documentation specific to the installed version.

## FAQ

### Does deepsec require a Vercel account?

By default, deepsec routes model calls through Vercel AI Gateway, which uses a Vercel project link. Passing --model-auth direct with --ai-provider and --ai-api-key-env to the init command switches to your own OpenAI or Anthropic key, and no Vercel account is needed in that mode.

### What does deepsec store in the .deepsec/ directory?

All scan state and findings live in .deepsec/, including the installed CLI, scan candidates, AI-generated findings, and the documentation for the installed version at .deepsec/node_modules/deepsec/SKILL.md. The directory is created at the repository root on first run and is not affected by interrupted runs.

### Can deepsec scan only the files changed in a pull request?

Yes. The process --diff command restricts the AI review to files changed in a specified diff. This is the PR-mode workflow documented in the reviewing-changes guide, and it is significantly cheaper than a full codebase scan.

## Sources

- [Official documentation](https://deepsec.sh/)
- [Official README](https://github.com/vercel-labs/deepsec#readme)
- [Project repository](https://github.com/vercel-labs/deepsec)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/vercel-labs-deepsec