⚡ Auto-Doc Engine

Clinical CTF writeup synthesis from raw terminal telemetry.

Auto-Doc Engine ingests raw, multi-domain CTF engagement logs — GDB sessions,
Burp Suite proxy output, nmap scans, SQL payloads, OSINT queries — and synthesizes
structured, portfolio-grade technical writeups automatically.

How It Works

Raw Telemetry  (file / stdin / pipe)
        │
        ▼
┌───────────────────────┐
│   Noise Filter        │  Strip ANSI codes, backspaces, ping loops,
│   filters/noise.py    │  nmap/gobuster boilerplate, repeated lines.
│                       │  Annotate failed attempts as [PIVOT] markers.
└──────────┬────────────┘
           │
           ▼
┌───────────────────────┐
│   Sanitizer           │  Redact IPv4/IPv6, MD5/SHA hashes, URL hosts.
│   filters/sanitizer.py│  Optional flag value redaction.
│                       │  Every replacement is logged for audit.
└──────────┬────────────┘
           │
           ▼
┌───────────────────────┐
│   Prompt Builder      │  Assemble clinical system prompt + telemetry
│   prompt_builder.py   │  into the 5-section writeup schema.
└──────────┬────────────┘
           │
           ▼
┌──────────────────────────────────────────────┐
│   AI Provider  (auto-cascade on failure)      │
│                                              │
│   1.  Google Gemini 2.5 Pro   (primary)      │
│   2.  Hugging Face Inference  (fallback)     │
│   3.  Ollama  local daemon    (last resort)  │
└──────────┬───────────────────────────────────┘
           │
           ▼
┌───────────────────────┐
│   Renderer            │  .md  (always)
│   renderers/          │  .html (dark-themed, self-contained)
│   markdown.py         │  .pdf  (via pandoc / wkhtmltopdf)
└───────────────────────┘

Output Schema

Every synthesized writeup enforces exactly five clinical sections:

Section	Content
Objective	One-sentence definition of the target and goal
Initial Enumeration	Exposed attack surface — ports, endpoints, services, metadata
Methodology & Pivots	Chronological attack path; failed attempts documented as `[PIVOT]`
Exploitation	Exact method + raw, unmodified final payload in a fenced code block
Impact / Flag	Final outcome; captured flag on its own line

Quick Start

git clone https://github.com/youruser/auto-doc-engine
cd auto-doc-engine
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
cp .env.example .env        # add your GEMINI_API_KEY

autodoc run \
  -f examples/demo_telemetry.txt \
  --name "HTB — SQL Injection Login Bypass" \
  --domain web --difficulty easy --preview

Installation

Requirements

Requirement	Version
Python	≥ 3.10
pandoc (optional, for PDF)	any

Steps

# 1. Clone
git clone https://github.com/parthispro/auto-doc-engine
cd auto-doc-engine

# 2. Create virtual environment
python3 -m venv .venv
source .venv/bin/activate       # Linux / macOS
# .venv\Scripts\activate        # Windows

# 3. Install
pip install -e .                # production
pip install -e ".[dev]"         # + pytest, ruff, black

# 4. Configure
cp .env.example .env
nano .env                       # add at least one API key

# 5. Verify
autodoc config
autodoc health

PDF support (optional)

# Ubuntu / Debian / Kali / linux
sudo apt install pandoc texlive-xetex

# macOS
brew install pandoc

AI Agent Plugin (v1.1.0+)

Auto-Doc Engine natively supports integration with AI agent ecosystems (such as Antigravity CLI and OpenCode). This allows your AI assistant to automatically detect CTF challenges, enforce physical telemetry tracking, and synthesize writeups securely.

Installing the Plugin

To enable the agent plugin for your workspace, ensure the .agents/plugins/autodoc-engine directory is present in your project.

# 1. Ensure the workspace supports .agents plugins
mkdir -p .agents/plugins

# 2. Copy the plugin from the Auto-Doc-Engine repository
cp -r path/to/auto-doc-engine/.agents/plugins/autodoc-engine .agents/plugins/

Usage Instructions

Once installed, the AI agent will inherit the following capabilities:

Keyword Activation: The agent will automatically enter "CTF Mode" and prompt for script or asciinema logging when it detects phrases like "find the flag" or "solve this CTF".
Force Activation: Send the message @autodoc to the agent to bypass ongoing tasks and force an immediate writeup generation.
OPSEC Compliance: The plugin natively enforces API key verification without writing to .bash_history and deterministically targets logs using the AUTODOC_TELEMETRY_PATH environment variable.

Configuration

All settings resolve in this priority order: Environment variable → ~/.autodoc/config.toml → .env file → built-in defaults

Variable	Default	Description
`AUTODOC_PROVIDER`	`auto`	Active provider: `gemini` · `huggingface` · `ollama` · `auto`
`GEMINI_API_KEY`	—	Google AI Studio key
`GEMINI_MODEL`	`gemini-3.5-flash-lite`	Gemini model name
`HF_API_KEY`	—	Hugging Face User Access Token
`HF_MODEL`	`mistralai/Mistral-7B-Instruct-v0.3`	HF model ID
`HF_ENDPOINT`	—	Custom HF Dedicated Endpoint URL (overrides serverless)
`OLLAMA_HOST`	`http://localhost:11434`	Ollama daemon URL
`OLLAMA_MODEL`	`llama3`	Local model to use
`AUTODOC_OUTPUT_DIR`	`./reports`	Output directory for all generated files
`AUTODOC_SANITIZE`	`true`	Enable/disable IP + hash redaction

Never commit .env — it's in .gitignore by default.

How to Run (CTF Workflow)

Auto-Doc Engine is built to capture your raw terminal telemetry during an engagement and synthesize it into a clinical writeup once complete.

Step 1: Start Recording (Before You Begin)

Open your terminal and initialize background logging using Linux's built-in script utility:

script -q ctf_session.log

Everything typed and printed in this shell (nmap, curl, gobuster, python scripts, gdb sessions, payloads) will be saved to ctf_session.log in real time with zero performance impact.

Step 2: Solve the Challenge Normally

Work through your reconnaissance, exploitation attempts, and pivots as usual:

# 1. Reconnaissance
nmap -sC -sV 10.10.11.50

# 2. Directory enumeration
gobuster dir -u http://10.10.11.50 -w /usr/share/wordlists/dirbuster/directory-list-2.3-medium.txt

# 3. Exploitation & Pivoting
curl -X POST http://10.10.11.50/login -d "user=admin' OR 1=1--"
# Note: Failed attempts are valuable — Auto-Doc detects them as [PIVOT] markers!

# 4. Final Flag Retrieval
# Working exploit retrieves the flag.

When you capture the flag, exit the recording session:

exit
# or press Ctrl + D

Step 3: Synthesize the Writeup

Activate the environment and generate your portfolio writeup:

source .venv/bin/activate

autodoc run \
  -f ctf_session.log \
  --name "HackTheBox — Challenge Title" \
  --domain web \
  --difficulty medium \
  --preview

What Happens Automatically

Noise Filtration: Strips raw ANSI escape color codes, backspace sequences, ping loops, and tool boilerplate banners.
Pivot Detection: Automatically extracts failed attempts (403 Forbidden, Connection refused, syntax errors) and marks them as [PIVOT] milestones demonstrating analytical rigor.
Clinical Sanitization: Replaces target IP addresses, hashes, and sensitive hostnames with clinical redaction markers ([REDACTED_PRIVATE_IP], [REDACTED_HOST]).
AI Synthesis: Passes cleaned telemetry to Gemini (or fallback providers) following the strict 5-section schema.
Multi-Format Export: Generates .md, styled dark-mode .html, and .pdf inside ./reports/.

Usage

Synthesize from a log file

autodoc run \
  --file session.log \
  --name "Web — Blind SQL Injection" \
  --domain web \
  --difficulty medium

Pipe from stdin

cat session.log | autodoc run --stdin \
  --name "Pwn — ret2libc" \
  --domain pwn \
  --difficulty hard

Record a live session and pipe directly

script -q -c "your_ctf_commands_here" /dev/stdout | \
  autodoc run --stdin --name "Live Session" --domain misc

Force a specific provider

autodoc run -f session.log --name "Crypto" --provider huggingface
autodoc run -f session.log --name "OSINT"  --provider ollama

Pass an API key inline (no `.env` needed)

autodoc run -f session.log --name "Test" \
  --provider gemini --api-key AIza...yourkey

Select output formats

# Only markdown
autodoc run -f session.log --name "Test" --format md

# Markdown + HTML only (skip PDF)
autodoc run -f session.log --name "Test" --format md --format html

Additional flags

Flag	Effect
`--preview` / `-v`	Print generated Markdown to terminal after synthesis
`--verbose`	Show pipeline steps and provider selection detail
`--redact-flags`	Also redact captured flag values in the output
`-o PATH`	Override output directory

Utility commands

autodoc health      # Ping all configured providers
autodoc models      # List locally available Ollama models
autodoc config      # Show resolved config (API keys masked)
autodoc --version   # Print version

AI Providers

Provider comparison

Provider	Quality	Speed	Cost	Requires
Google Gemini 2.5 Pro	★★★★★	Fast	API key (free tier available)	`GEMINI_API_KEY`
HuggingFace Inference	★★★☆☆	Medium	Free tier / paid	`HF_API_KEY`
Ollama (local)	★★★☆☆	Slow	Free	Running daemon

Auto-cascade fallback

When AUTODOC_PROVIDER=auto (the default):

Gemini  ──(fail)──►  HuggingFace  ──(fail)──►  Ollama

Every fallback is logged as a warning in the terminal summary.

Local Ollama setup

# Install
curl -fsSL https://ollama.com/install.sh | sh

# Start daemon
ollama serve

# Pull a model (one-time, ~4 GB)
ollama pull llama3

# Verify
autodoc models

Project Structure

auto-doc-engine/
│
├── src/autodoc/
│   ├── __init__.py             # Package version
│   ├── cli.py                  # Click CLI: run / health / models / config
│   ├── engine.py               # Pipeline orchestrator
│   ├── config.py               # Config loader (env / toml / .env / defaults)
│   ├── prompt_builder.py       # System + user prompt assembly
│   │
│   ├── filters/
│   │   ├── noise.py            # ANSI strip, ping collapse, PIVOT annotation
│   │   └── sanitizer.py        # IP / hash / URL / flag redaction
│   │
│   ├── providers/
│   │   ├── base.py             # Abstract BaseProvider interface
│   │   ├── __init__.py         # Registry + auto-cascade factory
│   │   ├── gemini.py           # Google Gemini backend
│   │   ├── huggingface.py      # HuggingFace Inference API backend
│   │   └── ollama.py           # Local Ollama backend
│   │
│   └── renderers/
│       └── markdown.py         # MD + dark HTML + PDF renderer
│
├── tests/
│   ├── test_sanitizer.py       # 10 sanitizer unit tests
│   └── test_noise.py           # 9 noise filter unit tests
│
├── examples/
│   └── demo_telemetry.txt      # Sample CTF web challenge session log
│
├── .env.example                # Config template (copy → .env)
├── .gitignore
├── pyproject.toml              # Build config + dependencies
├── LICENSE
├── CONTRIBUTING.md
└── CHANGELOG.md

Running Tests

# Activate venv first
source .venv/bin/activate

# Run all tests
pytest tests/ -v

# With coverage
pytest tests/ -v --tb=short

Expected: 19 passed in under 1 second.

Supported Security Domains

Flag	Domain
`pwn`	Binary exploitation, ROP chains, GDB/GEF sessions
`web`	SQLi, XSS, SSRF, Burp Suite / curl proxy logs
`crypto`	Cipher analysis, key extraction, Python crypto scripts
`osint`	Search queries, metadata extraction, relationship mapping
`rev`	Reverse engineering, disassembly, decompilation logs
`misc`	Everything else

Name		Name	Last commit message	Last commit date
.agents/plugins/autodoc-engine		.agents/plugins/autodoc-engine
.github		.github
examples		examples
src/autodoc		src/autodoc
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation

⚡ Auto-Doc Engine

Table of Contents

How It Works

Output Schema

Quick Start

Installation

Requirements

Steps

PDF support (optional)

AI Agent Plugin (v1.1.0+)

Installing the Plugin

Usage Instructions

Configuration

How to Run (CTF Workflow)

Step 1: Start Recording (Before You Begin)

Step 2: Solve the Challenge Normally

Step 3: Synthesize the Writeup

What Happens Automatically

Usage

Synthesize from a log file

Pipe from stdin

Record a live session and pipe directly

Force a specific provider

Pass an API key inline (no .env needed)

Select output formats

Additional flags

Utility commands

AI Providers

Provider comparison

Auto-cascade fallback

Local Ollama setup

Project Structure

Running Tests

Supported Security Domains

Contributing

Changelog

License

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Pass an API key inline (no `.env` needed)