<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0. See LICENSE for details. -->
<!-- NERF is a trademark of defconxt. -->

<div align="center">

<pre>
  ███╗   ██╗███████╗██████╗ ███████╗
  ████╗  ██║██╔════╝██╔══██╗██╔════╝
  ██╔██╗ ██║█████╗  ██████╔╝█████╗
  ██║╚██╗██║██╔══╝  ██╔══██╗██╔══╝
  ██║ ╚████║███████╗██║  ██║██║
  ╚═╝  ╚═══╝╚══════╝╚═╝  ╚═╝╚═╝
</pre>

**New Experimental Research Foundation — AI Security Engineering Platform**

[![Website](https://img.shields.io/badge/web-nerf.dev-00ff41.svg)](https://nerf.dev)
[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](LICENSE)
[![NERF CI](https://github.com/defconxt/NERF/actions/workflows/ci.yml/badge.svg)](https://github.com/defconxt/NERF/actions)
[![Node.js 22+](https://img.shields.io/badge/node-22+-00ff41.svg)](https://nodejs.org)
[![Skills](https://img.shields.io/badge/skills-1%2C563-00ff41.svg)](#skills)
[![Tests](https://img.shields.io/badge/tests-6%2C900_passing-00ff41.svg)](#development)
[![Frameworks](https://img.shields.io/badge/compliance-39_frameworks-00ff41.svg)](#compliance)
![GitHub stars](https://img.shields.io/github/stars/defconxt/NERF?style=social)

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](#install) · [Modes](#operating-modes) · [Skills](#skills) · [Engagement Engine](#engagement-engine) · [CLI](#cli) · [API](#api) · [Architecture](#architecture) · [nerf.dev](https://nerf.dev)

</div>

---

## Install

```bash
npm install -g @defconxt/nerf
```

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

```bash
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)**
```bash
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**
```bash
# 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)**
```bash
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)**
```bash
# 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)**
```bash
# 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)**
```bash
# 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**
```bash
# Sigma CLI: pipx install sigma-cli
# CALDERA: https://github.com/mitre/caldera#installation
# BloodHound: https://github.com/BloodHoundAD/BloodHound/releases
```

**Report Export**
```bash
# 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:

```bash
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):
```bash
# 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`:
```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:
```bash
export OLLAMA_BASE_URL=http://192.168.1.100:11434/v1
```

**LM Studio** (for models not available in Ollama — heretic/uncensored models, custom GGUF):
```bash
# 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`:
```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):
```yaml
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:

```yaml
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:
```yaml
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](https://agentskills.io):

| 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

```bash
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)

```bash
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)

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

### Compliance

39 frameworks, 1,151+ controls:

```bash
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:

```yaml
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`](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

```bash
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.

```bash
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](LICENSE)

Copyright (c) 2026 defconxt. All rights reserved. NERF is a trademark of [defconxt](https://github.com/defconxt).
