Fackel

Autonomous pentest framework powered by ReAct agents.
LLM-driven reconnaissance, scanning, triage, and report generation.

▶ Watch the Fackel interactive harness demo

The interactive harness — parallel agent lanes, a live pipeline stepper, and inline approval gates.

What is Fackel?

Fackel is a multi-agent pentest framework where LLMs decide what to do, not
hardcoded pipelines. Each specialist agent uses the
ReAct pattern (Reason + Act) to autonomously
choose which tools to call, interpret results, and decide next steps.

Target → OSINT → Approval Gate → Port Scan → Vuln Scan → Triage → Report
           ↕          ↕              ↕            ↕          ↕        ↕
       27 tools  Human-in-     2 tools      12 tools   LLM-as-   LLM
       (passive)  the-Loop      (active)     (active)   a-judge  synthesis

Key features

Quick start

Requirements

See docs/tools.md for the full list of required binaries per tool.

Automated tool install

# Install all external binaries automatically
./scripts/install-tools.sh

# Core tools only (nmap, naabu, nuclei, httpx, subfinder)
./scripts/install-tools.sh --minimal

# Audit — check which tools are installed/missing
./scripts/install-tools.sh --check

Install

# Clone and install
git clone https://github.com/your-org/fackel.git
cd fackel
uv sync --python 3.12

Or with pip:

python -m venv .venv && source .venv/bin/activate
pip install -e .

Configure

cp .env.example .env
# Edit .env — OPENAI_API_KEY is the only required key

Run

Interactive harness (recommended)

Run fackel with no arguments to launch the interactive harness — a REPL around
the agent pipeline with parallel agent lanes, inline approvals, and a knowledge
graph you can query (shown in the demo above):

fackel

Tip: the harness renders with Nerd Font glyphs.
No patched font? Set FACKEL_NERD_FONT=0 for an alignment-safe ASCII fallback.

One-shot scan

For CI or scripted runs, drive a single scan straight from the shell:

# Passive scan (OSINT only → report)
fackel scan example.com --no-active-scan

# Full scan (OSINT → port scan → vuln scan → triage → report)
fackel scan example.com

# Verbose mode — see LLM reasoning in real time
fackel scan example.com -v

# Save report to a specific file
fackel scan example.com -o report.md

# Check which provider API keys are configured
fackel scan example.com --check-providers --no-active-scan

Monitor changes across scans

# List persisted scans (requires the persistence store / data dir)
fackel scans

# Diff two scans — new / resolved / changed assets and findings
fackel diff <baseline-scan-id> <current-scan-id>

Pipeline overview

                     ┌─────────────────┐
                     │   osint_node    │ ← 27 passive tools
                     │  (ReAct agent)  │   dns, whois, subdomains, etc.
                     └────────┬────────┘
                              │
                    ┌─────────▼──────────┐
                    │  route_after_osint │
                    │  (conditional)     │
                    └──┬─────────────┬───┘
                       │             │
          active_scan  │             │  no active scan
          + IPs found  │             │  or no IPs
                       ▼             │
              ┌─────────────────┐    │
              │ approval_gate   │    │
              │ (HitL interrupt)│    │
              └───┬────────┬────┘    │
          approve │        │ reject  │
                  ▼        └────┐    │
           ┌────────────┐       │    │
           │ port_scan   │      │    │
           │ (ReAct)     │      │    │
           └─────┬───────┘      │    │
                 │              │    │
       ┌─────────▼───────────┐  │    │
       │route_after_port_scan│  │    │
       │(LLM-as-a-judge)     │  │    │
       └──┬──────────────┬───┘  │    │
          │              │      │    │
          ▼              ▼      │    │
   ┌────────────┐  ┌─────────┐  │    │
   │ vuln_scan  │  │ triage  │  │    │
   │ (ReAct)    │  │(struct) │◄      │
   └─────┬──────┘  └────┬────┘       │
         │              │            │
         ▼              │            │
   ┌──────────┐         │            │
   │  triage  │         │            │
   │ (struct) │         │            │
   └─────┬────┘         │            │
         │              │            │
         ▼              ▼            ▼
   ┌──────────────────────────────────┐
   │           report_node            │
   │         (LLM synthesis)          │
   └──────────────┬───────────────────┘
                  │
                 END

Each phase is a LangGraph node. The orchestrator manages state flow, conditional
routing, and accumulates findings across phases.

See docs/architecture.md for full architectural details.

Terminal UI

Fackel streams the whole run to the terminal in real time (see the demo
above). The renderer is built on Rich and
designed so you can follow autonomous agents at a glance:

Pass -v / --verbose to expand each phase's LLM reasoning and full tool-result
previews. Glyphs use a Nerd Font by default; set FACKEL_NERD_FONT=0 for an
alignment-safe ASCII rendering.

Specialist agents

See docs/agents.md for detailed agent documentation.

Tool inventory

See docs/tools.md for complete tool reference with input schemas and validation rules.

Configuration

Model per agent

Each agent reads its model from an environment variable, falling back to
gpt-5-mini:

# Use a more capable model for report generation
export FACKEL_MODEL_REPORT=gpt-4o

LLM provider

Fackel uses LangChain's init_chat_model and supports OpenAI (default) and Ollama (local-first).

OpenAI

The default LLM provider. Requires OPENAI_API_KEY:

export OPENAI_API_KEY=sk-...
export FACKEL_DEFAULT_MODEL=gpt-5-mini
# or per-agent:
export FACKEL_MODEL_REPORT=gpt-4o

Ollama

Run LLMs locally with Ollama. Install Ollama, then pull a tool-calling-capable model:

ollama pull llama3.1
# or: ollama pull qwen2.5

Set environment variables:

export FACKEL_LLM_PROVIDER=ollama
export FACKEL_DEFAULT_MODEL=llama3.1
# Optional — default is http://localhost:11434
export FACKEL_OLLAMA_BASE_URL=http://ollama.internal:11434

Or use the provider:model prefix syntax to override per-agent:

export FACKEL_MODEL_REPORT=ollama:llama3.1
export FACKEL_MODEL_OSINT=openai:gpt-4o-mini

Model requirements: ReAct agents need tool-calling support. Recommended Ollama models:
llama3.1, llama3.2, qwen2.5, qwen2.5-coder, mistral-nemo, mistral (≥ v0.3), command-r.
Models without tool support work for simple text generation but will fail in scanning agents.

Per-agent override

Mix providers and models across agents:

export FACKEL_MODEL_OSINT=openai:gpt-4o-mini      # Fast OpenAI model
export FACKEL_MODEL_REPORT=ollama:qwen2.5         # Local Ollama
export FACKEL_MODEL_VULN_SCAN=openai:gpt-4o       # Capable OpenAI model

API keys

Tools with missing API keys (and hard_fail=True) are automatically removed
from agents, preventing the LLM from attempting calls that would fail.

Infrastructure (optional)

# Start MongoDB persistence stack
docker compose up -d

The docker-compose.yml provides:

• MongoDB 7 — scan persistence and query system

Observability (optional)

Fackel uses LangSmith for LLM observability. Set the env vars and all
agent traces appear automatically:

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=lsv2_pt_...
export LANGSMITH_PROJECT=fackel

See docs/configuration.md for full configuration reference.

Python API

from fackel.agents.orchestrator import run

# Blocking — returns final state
result = run("example.com", active_scan=True)
print(result["report"])

Adding new tools

1. Create a new file in src/tools/ with a @tool-decorated function and
   Pydantic input schema:

# src/tools/recon/my_tool.py
from langchain_core.tools import ToolException, tool
from pydantic import BaseModel, Field

from fackel.tooling import TargetType, format_tool_output, guard_target


class MyToolInput(BaseModel):
    target: str = Field(description="Domain or IP to scan.")

@tool(args_schema=MyToolInput)
def my_recon_tool(target: str) -> dict:
    """Describe what this tool does — the LLM reads this docstring."""
    target = guard_target(target, "my_recon_tool", TargetType.HOST)
    #  guard_target raises ToolException on invalid input

    # ... implementation ...
    return format_tool_output("my_recon_tool", target, "success", data=result)

# Enable LangChain error propagation — the LLM sees errors as tool results.
my_recon_tool.handle_tool_error = True  # type: ignore[attr-defined]

1. Import and add it to the relevant agent's tools list.

2. The LLM will autonomously decide when and how to use it based on
   its docstring and the agent's system prompt.

See docs/development.md for the full development guide.

Documentation

Development

# Install dev dependencies
uv sync --python 3.12 --extra dev

# Lint
uv run ruff check src/

# Type check
uv run mypy src/

# Tests
uv run pytest tests/

# Format
uv run ruff format src/

License

Apache 2.0 — see LICENSE.