GitHub - defconxt/NERF: AI Security Engineering Platform

  ███╗   ██╗███████╗██████╗ ███████╗
  ████╗  ██║██╔════╝██╔══██╗██╔════╝
  ██╔██╗ ██║█████╗  ██████╔╝█████╗
  ██║╚██╗██║██╔══╝  ██╔══██╗██╔══╝
  ██║ ╚████║███████╗██║  ██║██║
  ╚═╝  ╚═══╝╚══════╝╚═╝  ╚═╝╚═╝

New Experimental Research Foundation — AI Security Engineering Platform

AI security engineering platform and autonomous coding agent. 1,563 techniques across 117 domains, 9 auto security modes, cross-session memory, RAG over 96 knowledge docs, compliance automation for 39 frameworks, scanning pipelines, and a full REST API. Built on pi-mono (@nerf/pi-ai) with 26 LLM providers including local Ollama and LM Studio. Pure Node.js.

Install · Modes · Skills · Engagement Engine · CLI · API · Architecture · nerf.dev

Install

npm install -g @defconxt/nerf

All dependencies, including the LLM layer (pi-mono / @nerf/pi-ai, 26 providers), install automatically.

nerf setup        # Configure LLM backend and API keys
nerf doctor       # Verify installation — shows all tool status

Optional Security Tools

NERF works without any of these, but they unlock the scanning, exploitation, forensics, and OSINT pipelines. Run nerf doctor at any time to see what's installed.

Scanning & Recon (RED/BLUE/PURPLE)

go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest
go install -v github.com/projectdiscovery/katana/cmd/katana@latest
go install -v github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest
go install -v github.com/projectdiscovery/httpx/cmd/httpx@latest

Red Team

# Kali/Debian: apt install nmap sqlmap ffuf gobuster hydra metasploit-framework
# Arch: pacman -S nmap sqlmap gobuster hydra
# Sliver C2: curl https://sliver.sh/install | sudo bash
# John/Hashcat: apt install john hashcat

OSINT (RECON)

pip install sherlock-project holehe
# exiftool: apt install libimage-exiftool-perl / pacman -S perl-image-exiftool
# amass: go install -v github.com/owasp-amass/amass/v4/...@master

Forensics & Reverse Engineering (INCIDENT)

# Volatility 3: pip install volatility3
# YARA: apt install yara / pacman -S yara
# Radare2: apt install radare2 / pacman -S radare2
# Ghidra: https://ghidra-sre.org (requires JDK 17+)
# binwalk: pip install binwalk

Network (RED/BLUE)

# Wireshark/tshark: apt install wireshark / pacman -S wireshark-qt
# masscan: apt install masscan / pacman -S masscan
# Nikto: apt install nikto / pacman -S nikto

DevSecOps (BUILD)

# Grype (vulnerability scanner): curl -sSfL https://raw.githubusercontent.com/anchore/grype/main/install.sh | sh
# Syft (SBOM): curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh
# Cosign: go install github.com/sigstore/cosign/v2/cmd/cosign@latest

Blue/Purple Team

# Sigma CLI: pipx install sigma-cli
# CALDERA: https://github.com/mitre/caldera#installation
# BloodHound: https://github.com/BloodHoundAD/BloodHound/releases

Report Export

# PDF via weasyprint: pip install weasyprint
# PDF via wkhtmltopdf: apt install wkhtmltopdf / pacman -S wkhtmltopdf

LLM Backends

All backends route through @nerf/pi-ai (pi-mono). 26 providers supported. Configure one in ~/.config/nerf/config.yaml or via environment variables.

Cloud Providers (API Key)

Backend	Environment Variable	Notes
Claude (Anthropic)	`ANTHROPIC_API_KEY=sk-ant-...`	Default. Sonnet/Opus/Haiku models.
Gemini (Google)	`GEMINI_API_KEY=...`	Gemini 2.5 Pro/Flash models.
OpenAI	`OPENAI_API_KEY=sk-...`	GPT-4o, o1, o3 models.
OpenRouter	`OPENROUTER_API_KEY=...`	200+ models via single API.
Mistral	`MISTRAL_API_KEY=...`	Mistral Large/Medium/Small.
Groq	`GROQ_API_KEY=...`	Ultra-fast inference (llama, mixtral).
xAI	`XAI_API_KEY=...`	Grok models.

OAuth (Claude Code)

NERF supports OAuth authentication for Claude — no API key required:

nerf setup    # Follow the OAuth flow to authenticate with your Anthropic account

Credentials are stored in ~/.nerf/agent/auth.json and auto-refreshed. This is the same auth used by Claude Code.

Local Providers

Ollama (recommended for local inference):

# Install: https://ollama.ai
ollama serve                          # Start the server (runs on port 11434)
ollama pull qwen2.5:32b               # Pull a model

Configure in ~/.config/nerf/config.yaml:

llm_backend: ollama
ollama:
  base_url: "http://127.0.0.1:11434/v1"
  model: "qwen2.5:32b"
  timeout: 300

Or point to any running Ollama instance:

export OLLAMA_BASE_URL=http://192.168.1.100:11434/v1

LM Studio (for models not available in Ollama — heretic/uncensored models, custom GGUF):

# Install: https://lmstudio.ai/download
# 1. Open LM Studio and download your model via the Discover tab
# 2. Start the local server: Local Server tab → Start Server (port 1234)
# 3. Or via CLI (requires LM Studio app running):
lms server start --port 1234

Configure in ~/.config/nerf/config.yaml:

llm_backend: openai-compat
openai-compat:
  base_url: "http://127.0.0.1:1234/v1"
  api_key: "lm-studio"          # any non-empty string
  model: "your-model-name"      # must match the loaded model in LM Studio
  timeout: 300

Note: LM Studio's lms CLI requires the LM Studio desktop app to be running as a daemon. On headless Linux servers, start LM Studio with DISPLAY=:0 lm-studio --no-sandbox & before running lms server start.

Any OpenAI-compatible endpoint (vLLM, Together, Cerebras, custom):

llm_backend: openai-compat
openai-compat:
  base_url: "https://your-endpoint/v1"
  api_key: "${YOUR_API_KEY}"
  model: "your-model-id"

Per-Phase Model Routing

Use expensive models where quality matters, cheaper/faster models for speed:

models:
  research: "openrouter/deepseek/deepseek-r1"
  planning:
    model: "claude-opus-4-6"
    fallbacks:
      - "openrouter/anthropic/claude-3.5-sonnet"
  execution: "claude-sonnet-4-6"
  completion: "claude-sonnet-4-6"

Mix local and cloud models across phases:

models:
  research: "ollama/qwen2.5:32b"       # free local for research
  planning: "claude-opus-4-6"          # best quality for planning
  execution: "claude-sonnet-4-6"       # fast cloud for execution

Operating Modes

9 modes, auto-detected from your query via weighted keyword scoring:

Mode	Focus
🔴 RED	Attack paths, exploitation, C2, lateral movement. Sub-routes to web, AD, cloud, post-exploitation.
🔵 BLUE	Detection engineering, Sigma/KQL/SPL rules, hardening, threat hunting.
🟣 PURPLE	ATT&CK mapping, adversary emulation, detection coverage, gap analysis.
🟢 PRIVACY	GDPR, CCPA, HIPAA, DPIAs, data flow analysis, OpSec.
🔍 RECON	OSINT, passive/active recon, asset discovery, footprinting.
🚨 INCIDENT	Triage, digital forensics, containment, eradication, timeline reconstruction.
🏗️ ARCHITECT	Zero trust, threat modeling (STRIDE/DREAD/PASTA), defense-in-depth.
🔧 BUILD	Security tooling, automation, CI/CD security, IaC. Layers with other modes.
🔬 RESEARCHER	Vulnerability research, CVE analysis, threat intel synthesis.

BUILD layers on top of any mode: RED+BUILD produces offensive tools, BLUE+BUILD produces defensive automation.

Background layers always active: RED outputs include detection opportunities, BLUE outputs include evasion considerations, any output touching data flags privacy implications.

Skills

1,563 techniques across 117 domains following the AgentSkills specification:

Category	Domains
Offensive	red-team (web, AD, cloud, post-exploitation), exploit-development, binary-exploitation, c2-frameworks, bug-bounty, social-engineering
Defensive	blue-team, soc-operations, detection-engineering, incident-response, endpoint-security, network-security, ransomware-defense, phishing-defense, email-security
Application	application-security, api-security, secure-coding, devsecops, security-testing, nuclei-templating, pr-security-review
Cloud & Infra	cloud-security, cloud-native-security, container-security, database-security, zero-trust
Identity & Data	identity-access-management, data-security, cryptography, privacy-engineering
Intelligence	threat-intelligence, malware-analysis, digital-forensics, cloud-forensics, osint-recon, reverse-engineering, log-analysis
Governance	compliance-audit, governance-risk-compliance, vulnerability-management, supply-chain-security, security-awareness, security-leadership
Engineering	automation-scripting, security-operations-automation, security-data-engineering

RAG pipeline: 96 knowledge docs chunked into 17,800+ segments, indexed in FTS5 (SQLite), top-5 retrieval injected into system prompt per query.

Engagement Engine

NERF includes a spec-driven execution engine for sustained, multi-session security work.

Work Decomposition

Engagement (E001)  ->  a complete security assessment
  Campaign (C01)   ->  one demoable vertical capability
    Task (T01)     ->  one context-window-sized unit of work

Lifecycle

Command	Action
`/nerf:engage`	Start a new engagement (pentest, IR, audit, tool build)
`/nerf:auto`	Enter auto mode: research, plan, execute, verify, repeat
`/nerf:stop`	Gracefully stop auto mode
`/nerf:status`	Progress dashboard with cost tracking
`/nerf:resume`	Resume engagement with state summary
`/nerf:discuss`	Discuss architecture/tactics alongside auto mode
`/nerf:steer`	Hard-steer plan documents during execution
`/nerf:queue`	Queue future campaigns
`/nerf:export`	Export engagement as formatted security report

Auto Mode

The execution engine reads .nerf/, determines the next unit of work, creates a fresh agent session with pre-loaded context, dispatches, verifies, and loops.

Fresh session per task: clean context window, no accumulated garbage
Context pre-loading: plans, summaries, decisions, knowledge injected before each dispatch
Git worktree isolation: each engagement runs on an engagement/<EID> branch
Crash recovery: lock file tracking, stale lock detection, automatic recovery
Stuck detection: sliding-window detector halts after repeated dispatch of same unit
Budget enforcement: stops when configured ceiling reached
Verification enforcement: configurable commands run after each task with auto-fix retries
Per-phase model routing: different models for research, planning, execution, completion

Artifacts

.nerf/
  STATE.md                    Quick-glance dashboard
  ENGAGEMENT.md               Active scope, targets, constraints
  DECISIONS.md                Append-only decisions register
  KNOWLEDGE.md                Cross-session patterns and lessons
  engagements/E001/
    E001-ROADMAP.md           Campaign plan with checkboxes
    E001-CONTEXT.md           Operator decisions from discuss phase
    E001-RESEARCH.md          Target and ecosystem research
    campaigns/C01/
      C01-PLAN.md             Task decomposition
      C01-FINDINGS.md         Security findings
      tasks/
        T01-PLAN.md           Task plan with must-haves
        T01-SUMMARY.md        What happened (YAML frontmatter + narrative)

CLI

nerf scan https://example.com          # Vulnerability scan
nerf review ./src                       # Security code review
nerf compliance SOC2                    # Compliance assessment
nerf osint example.com                  # OSINT investigation
nerf "how do I detect Kerberoasting"    # Natural language query

nerf red --auto "pentest the target"    # Auto execution engine
nerf api                                # Start REST API server
nerf mcp                                # Start MCP server (stdio)
nerf bot                                # Start Signal bot

Security Mode Commands

/nerf:redteam /nerf:hunt /nerf:sigma /nerf:hardening /nerf:forensics /nerf:purple /nerf:recon /nerf:privacy /nerf:insider /nerf:threatmodel /nerf:cloud /nerf:crypto /nerf:devsecops /nerf:ir /nerf:cve /nerf:threatintel /nerf:aisec /nerf:audit /nerf:web /nerf:phishing /nerf:malware /nerf:mobile /nerf:ics

Utility Commands

/nerf:brief /nerf:report /nerf:update /nerf:setup-hooks /nerf:doctor /nerf:forensics-debug /nerf:keys /nerf:logs

API

REST API (16 endpoints)

nerf api --port 8443

Scan, diff, secrets detection, memory store/search, compliance, skills search, leaderboard. HMAC-SHA256 auth, rate limiting, CORS.

MCP Server (10 tools)

{
  "mcpServers": {
    "nerf": { "command": "nerf", "args": ["mcp"] }
  }
}

Compliance

39 frameworks, 1,151+ controls:

nerf compliance NIST_800_53 --format json
nerf compliance GDPR --format markdown
nerf compliance PCI_DSS --format csv

NIST 800-53, CIS v8, SOC 2, PCI DSS 4.0, HIPAA, GDPR, CCPA, ISO 27001, FedRAMP, CMMC, EU AI Act, and 28 more.

Architecture

@defconxt/nerf
├── dist/loader.js                   Entry point, command routing
├── cli/lib/
│   ├── gateway/                    Mode detection, prompt assembly, LLM client, commands
│   ├── agent-runtime/              SKILL.md parser, domain handlers
│   ├── memory/                     SQLite + FTS5 cross-session memory
│   ├── knowledge/                  FTS5 RAG index (96 docs, 17,800+ chunks)
│   ├── pipeline/                   Nuclei/Katana scanning, OSINT, SARIF
│   ├── review/                     3-layer security code review
│   ├── benchmark/                  3 CTF suites (NYU CTF, PicoCTF, OverTheWire)
│   ├── api/                        REST server (16 endpoints), compliance engine
│   ├── bot/                        Signal bot
│   ├── tools/                      NERF tool implementations
│   ├── guardrails/                 Security guardrails and gates
│   └── export/                     Report generation and templates
├── packages/
│   ├── pi-ai/                      @nerf/pi-ai — unified LLM API, 26 providers (pi-mono)
│   ├── pi-agent-core/              @nerf/pi-agent-core — agent loop, steer() (pi-mono)
│   ├── pi-coding-agent/            @nerf/pi-coding-agent — session management (pi-mono)
│   ├── pi-tui/                     @nerf/pi-tui — terminal UI components (pi-mono)
│   ├── native/                     Rust N-API bindings — high-performance native modules
│   ├── mcp-server/                 MCP server — NERF tools for Claude Code, Cursor, etc.
│   ├── daemon/                     Background process for project monitoring
│   └── rpc-client/                 Standalone RPC client SDK
├── src/resources/
│   ├── skills/                     1,563 SKILL.md + 1,441 agent.js
│   ├── agents/                     18 agent definitions
│   └── extensions/
│       └── nerf/                   Pi extension: 10 tools, 34 slash commands, hooks
├── knowledge/                      96 deep-dive security docs
└── .nerf/                          Engagement state directory

Pi Runtime (pi-mono)

NERF's LLM layer is built on pi-mono, a runtime that ships as vendored @nerf/* packages:

Package	Version	Role
`@nerf/pi-ai`	0.57.1	Unified LLM API — 26 providers, single streaming interface
`@nerf/pi-agent-core`	0.57.1	Agent loop, tool dispatch, `steer()` for mid-run pivots
`@nerf/pi-coding-agent`	1.2.9	Session management, extension API, interactive mode
`@nerf/pi-tui`	0.57.1	Terminal UI, statusline, progress display

All LLM operations route through @nerf/pi-ai. Zero direct SDK imports anywhere in the codebase. Enforced by CI guardrail tests that fail on any direct @anthropic-ai/sdk, openai, or provider SDK import outside of packages/.

The 26 supported providers include: Anthropic (Claude + OAuth), OpenAI, Google (Gemini), Ollama, LM Studio, OpenRouter, Mistral, Groq, xAI, Azure OpenAI, Amazon Bedrock, Google Vertex AI, HuggingFace, Cerebras, Together, Perplexity, Cohere, Fireworks, DeepSeek, and any OpenAI-compatible endpoint.

Provider SDKs bundled in @nerf/pi-ai: @anthropic-ai/sdk, openai, @google/genai, @mistralai/mistralai, @aws-sdk/client-bedrock-runtime, @anthropic-ai/vertex-sdk.

Core Dependencies

@nerf/pi-ai            26 LLM providers, unified streaming API, OAuth support
@nerf/pi-agent-core    Agent loop, steer(), tool call dispatch
@nerf/pi-coding-agent  Session management, extension API
@nerf/pi-tui           Terminal UI, interactive components
better-sqlite3         Memory engine, FTS5 knowledge index, leaderboard
playwright             Browser automation (browser tools extension)
ws                     Signal bot WebSocket
yaml                   Config parsing with env var substitution
undici                 HTTP client for API and scan pipelines

Configuration

Config file: config.yaml (project root) or ~/.config/nerf/config.yaml. Supports ${VAR} and ${VAR:-default} environment variable substitution. Priority: env vars > project config > user config.

Key settings:

llm_backend: claude           # claude | ollama | openai | openai-compat | google | mistral | pi-ai
models:                       # Per-phase model routing — mix local and cloud freely
  research: claude-sonnet-4-6
  planning: claude-opus-4-6
  execution: claude-sonnet-4-6
  completion: claude-sonnet-4-6
auto_supervisor:
  soft_timeout_minutes: 20
  hard_timeout_minutes: 30
budget_ceiling: 50.00         # USD — auto mode stops when reached
verification_commands:        # Run after each task, failure blocks progression
  - npm run test
token_profile: balanced       # budget | balanced | quality

See config.yaml.example for all options including LM Studio, Groq, vLLM, and Bedrock.

Hooks

NERF includes Claude Code hooks that install via /nerf:setup-hooks:

Statusline: model, directory, engagement status, context usage bar
Context monitor: warns at 35% remaining (WARNING) and 25% (CRITICAL), engagement-aware messaging
Pre-commit scan: detects hardcoded secrets, dangerous patterns, .env files in staged changes

Development

git clone https://github.com/defconxt/NERF.git && cd NERF
npm install
npm run build
npm test            # Unit + integration tests (2,399+ passing)

Node.js 22+ required. ESM modules throughout. Tests: vitest (2,399 tests, 96 files) + node:test unit suite + smoke suite (106 checks). All LLM calls route through @nerf/pi-ai. Zero direct provider SDK imports, enforced by CI guardrail tests.

npm run typecheck:extensions  # TypeScript check — 0 errors
npm run test:vitest           # 96/96 files, 2399/2399 tests
npm run test:smoke            # 4/4 smoke tests (106 internal checks)

License

AGPL-3.0

Name		Name	Last commit message	Last commit date
Latest commit History 53 Commits
.github		.github
cli		cli
completions		completions
data/compliance		data/compliance
docker		docker
docs		docs
hooks		hooks
knowledge		knowledge
mappings		mappings
native		native
packages		packages
pkg		pkg
scripts		scripts
src		src
tests		tests
web		web
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.npmignore		.npmignore
.npmrc		.npmrc
.secretscanignore		.secretscanignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
Modelfile		Modelfile
README.md		README.md
RELEASE-STATE.json		RELEASE-STATE.json
config.yaml.example		config.yaml.example
package-lock.json		package-lock.json
package.json		package.json
tsconfig.extensions.json		tsconfig.extensions.json
tsconfig.json		tsconfig.json
tsconfig.resources.json		tsconfig.resources.json
tsconfig.test.json		tsconfig.test.json

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Install

Optional Security Tools

LLM Backends

Cloud Providers (API Key)

OAuth (Claude Code)

Local Providers

Per-Phase Model Routing

Operating Modes

Skills

Engagement Engine

Work Decomposition

Lifecycle

Auto Mode

Artifacts

CLI

Security Mode Commands

Utility Commands

API

REST API (16 endpoints)

MCP Server (10 tools)

Compliance

Architecture

Pi Runtime (pi-mono)

Core Dependencies

Configuration

Hooks

Development

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 15

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages