<!-- 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>

**AI Security Engineering Platform**

[![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 for 26 LLM providers. Pure Node.js.

[Install](#install) · [Modes](#operating-modes) · [Skills](#skills) · [Engagement Engine](#engagement-engine) · [CLI](#cli) · [API](#api) · [Architecture](#architecture)

</div>

---

## Install

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

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

```bash
nerf setup        # Configure LLM backend
nerf doctor       # Verify installation
```

**Optional** (NERF works without these):

```bash
go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest
go install -v github.com/projectdiscovery/katana/cmd/katana@latest
```

### LLM Backends

All backends route through pi-mono. Configure one:

| Backend | Setup |
|---------|-------|
| **Claude** | `export ANTHROPIC_API_KEY=sk-ant-...` |
| **Ollama** (local, free) | [Install Ollama](https://ollama.ai), then `ollama serve` |
| **OpenAI** | `export OPENAI_API_KEY=sk-...` |
| **OpenRouter** | Configure in `~/.config/nerf/config.yaml` |
| **Any OpenAI-compatible** | Configure `openai-compat` backend |

Per-phase model routing: use expensive models for planning, cheaper models for research and execution.

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

### Pi Extension

NERF also runs as a native [pi](https://github.com/badlogic/pi-mono) extension:

```bash
pi install @defconxt/nerf
```

---

## 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 v2 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
├── src/resources/
│   ├── skills/                     1,563 SKILL.md + 1,441 agent.js
│   ├── agents/                     18 agent definitions
│   └── extensions/
│       └── nerf/                   Pi extension: tools, commands, hooks, 34 prompt templates
├── knowledge/                      96 deep-dive security docs
└── .nerf/                          Engagement state directory
```

### LLM Layer

All LLM operations route through pi-mono (`@nerf/pi-ai`). 26 providers including Anthropic, OpenAI, Google, Ollama, OpenRouter, Mistral, and any OpenAI-compatible endpoint. Zero direct SDK imports, enforced by CI guardrail tests.

### Dependencies

```
@nerf/pi-ai            26 LLM providers, unified streaming API
@nerf/pi-agent-core    Agent loop with steer() for mid-execution pivots
@nerf/pi-coding-agent  Session management, tool dispatch
@clack/prompts                 Interactive CLI prompts
better-sqlite3                 Memory engine, knowledge FTS5 index
ws                             Signal bot WebSocket
yaml                           Config parsing
```

---

## 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
models:                          # Per-phase model routing
  research: openrouter/deepseek/deepseek-r1
  execution: 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
  - npm run test
token_profile: balanced          # budget | balanced | quality
```

See [`config.yaml.example`](config.yaml.example) for all options.

---

## 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 (~6,900 tests)
```

Node.js 22+ with ESM modules. Tests use node:test and vitest. All LLM calls route through pi-mono. Zero direct SDK imports, enforced by CI guardrail tests.

---

## License

[AGPL-3.0](LICENSE)

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