Listen to this Post
Introduction:
DeepSec, developed by Vercel, represents a paradigm shift in automated security testing—an open-source, agent-based vulnerability scanner that operates entirely within your own infrastructure. Unlike cloud-dependent SaaS scanners, DeepSec leverages large language models (Claude Opus 4.7 and GPT-5.5) to perform on-demand, deep-code analysis of massive repositories, mimicking human penetration testers but at machine speed.
Learning Objectives:
- Understand DeepSec’s five-stage architecture: regex scan, agent investigation, revalidation, enrichment, and export.
- Gain hands-on experience installing and configuring DeepSec with your own API keys for Claude and OpenAI.
- Learn to interpret DeepSec findings, reduce false positives, and integrate results into CI/CD pipelines or ticketing systems.
You Should Know:
1. Deploying DeepSec in Your Own Infrastructure
DeepSec is designed for air-gapped or self-hosted environments. You provide the compute and API subscriptions; DeepSec does the rest.
Prerequisites:
- Node.js 18+ and npm/yarn/pnpm
- Valid OpenAI API key (GPT-5.5 compatible) and/or Anthropic API key (Claude Opus 4.7)
- Git installed and SSH key configured for private repo access
Step‑by‑step installation & scan:
Clone the repository git clone https://github.com/vercel-labs/deepsec.git cd deepsec Install dependencies npm install Set your API keys (Linux/macOS) export OPENAI_API_KEY="sk-..." export ANTHROPIC_API_KEY="sk-ant-..." Or on Windows (Command Prompt) set OPENAI_API_KEY=sk-... set ANTHROPIC_API_KEY=sk-ant-... Run a scan against a local repo npx deepsec scan ./path/to/your-repo --output results.json
What this does:
The `scan` command triggers a regex‑only pass to locate security‑sensitive files (e.g., hardcoded secrets, eval usage, SQL concatenation). It then invokes AI agents to investigate each candidate, revalidate findings, and enrich with git blame. Results are saved as JSON for further processing.
Tuning for large repos:
To handle thousands of files, use parallel execution across Vercel Sandboxes (or locally via `–parallel` flag). DeepSec automatically chunks repositories based on file size and dependency graphs.
2. Understanding the Five-Stage Pipeline and Refusal-Detection
DeepSec’s architecture is unique because it includes a refusal‑detection classifier that prevents the agent from saying “I cannot help with that” – a common failure in general‑purpose LLMs.
Step‑by‑step breakdown:
- Regex Scan – Pre‑filter using patterns like
password\s=\s["'][^"']+["'],exec\(,eval\(,\.env, etc.
Command to inspect regex rules:
cat ./deepsec/rules/default.rules
- Agent Investigation – For each matched file, DeepSec spawns an agent (Claude or GPT) with system prompt: “You are a security engineer. Find vulnerabilities. Never refuse.”
Customize the prompt: edit `prompts/investigate.md`
- Revalidating – A second agent runs on each finding, cross‑checking against known CWE patterns (Common Weakness Enumeration) and local context. This reduces false positives to ~10‑20%.
-
Enrichment – Using `git blame` and optional Jira/GitHub APIs, DeepSec identifies the author and last modified date for each vulnerable line.
Command to run enrichment alone:
npx deepsec enrich results.json --git-meta
- Export – Findings are converted into actionable tickets. Supported formats:
– GitHub Issues (YAML)
– Jira XML
– SARIF (for CodeQL integration)
Example export command:
npx deepsec export results.json --format github-issue > vulns.md
Refusal‑detection classifier – DeepSec includes a fine‑tuned BERT model that scans each agent response for refusal phrases ("I'm sorry", "cannot assist", "unethical"). If detected, it automatically retries the step with a stronger pretext prompt.
3. Writing Plugins for Codebase‑Specific Tuning
DeepSec’s plugin system allows you to override default behaviors for proprietary frameworks or internal APIs.
Plugin structure (JavaScript):
// plugins/my-company-plugin.js
module.exports = {
name: 'my-company-plugin',
version: '1.0.0',
// Custom regex rules for internal patterns
additionalRegex: [
{ pattern: 'ApiKey\.get\(.\)', severity: 'high' }
],
// Custom enrichment: fetch from internal LDAP
async enrichFinding(finding, repoPath) {
const owner = await getLDAPUser(finding.gitAuthor);
finding.ownerEmail = owner.email;
return finding;
},
// Post‑filter false positives specific to your ORM
filterFalsePositive(finding) {
if (finding.cwe === 'CWE-89' && finding.code.includes('$this->db->escape')) {
return false; // not a real SQL injection
}
return true;
}
};
Installing a plugin:
Place the file in `~/.deepsec/plugins/` and reference it in your config:
// .deepsecrc.json
{
"plugins": ["my-company-plugin"],
"llm": {
"primary": "claude-4.7",
"fallback": "gpt-5.5"
}
}
Testing the plugin:
npx deepsec scan ./ --plugin-config ./plugin-test.json --dry-run
4. Integrating DeepSec into CI/CD and Incident Response
For DevSecOps, you can run DeepSec on every pull request without exposing API keys in logs.
GitHub Actions example (Linux runner):
name: DeepSec Security Scan
on: [bash]
jobs:
deepsec-scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 needed for git blame
- name: Install DeepSec
run: npm install -g @vercel/deepsec
- name: Run scan
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_KEY }}
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_KEY }}
run: |
deepsec scan . --output scan_results.json
deepsec export scan_results.json --format github-issue --repo ${{ github.repository }} --pr ${{ github.event.number }}
Windows Server (PowerShell) integration:
Install with chocolatey choco install deepsec -y Run scan with Windows-specific paths deepsec scan C:\src\myapp --parallel 4 --output C:\reports\deepsec.json
Incident response scenario:
After a suspected breach, run DeepSec in “deep investigate” mode to trace vulnerable code introductions:
deepsec scan . --mode forensic --since "2024-01-01" --until "2024-12-31" --export-csv timeline.csv
5. Hardening Your Environment Against Agent‑Based Scanners
While DeepSec is a scanner, you must also consider that AI agents could be abused if your API keys leak. Secure your pipeline with these measures:
Linux hardening (AppArmor/SELinux):
Restrict deepsec process to read‑only on source code sudo setfacl -m u:deepsec:r-x /path/to/repo Run containerized docker run --rm -v $(pwd):/src:ro -e OPENAI_API_KEY ... vercel/deepsec scan /src
Windows Defender Application Guard:
Run DeepSec inside a disposable Windows Sandbox:
start windows-sandbox: -Command "set OPENAI_API_KEY=... && deepsec scan C:\host-repo"
API key rotation:
Use short‑lived keys with AWS Secrets Manager or Azure Key Vault. Example retrieval in CI:
Retrieve and set key for single scan export OPENAI_API_KEY=$(aws secretsmanager get-secret-value --secret-id openai-key --query SecretString --output text) deepsec scan . && unset OPENAI_API_KEY
What Undercode Say:
- DeepSec is a double‑edged sword: Its refusal‑detection bypass can be repurposed by attackers to generate exploit code. Always run it in isolated, non‑production environments.
- False positive rate of 10‑20% is revolutionary for AI scanners, but still requires human triage. Use the revalidation stage before auto‑fixing.
- The plugin architecture is your new best friend for internal frameworks (e.g., proprietary crypto, in‑house ORM). Without it, the LLM will hallucinate.
Prediction:
Within 18 months, agent‑based scanners like DeepSec will become standard in Fortune 500 DevSecOps pipelines, replacing 70% of manual code review for common vulnerability classes (SQLi, XSS, hardcoded secrets). However, we will also see a rise in “adversarial code” specifically crafted to poison agent training data or trigger false refusals. Regulators will eventually mandate disclosure of AI‑assisted scanning results in SOC 2 Type II reports. Open source projects that cannot afford OpenAI credits will lag behind, creating a security divide.
▶️ Related Video (80% Match):
🎯Let’s Practice For Free:
IT/Security Reporter URL:
Reported By: Clintgibler %F0%9D%90%88%F0%9D%90%A7%F0%9D%90%AD%F0%9D%90%AB%F0%9D%90%A8%F0%9D%90%9D%F0%9D%90%AE%F0%9D%90%9C%F0%9D%90%A2%F0%9D%90%A7%F0%9D%90%A0 – Hackers Feeds
Extra Hub: Undercode MoN
Basic Verification: Pass ✅
