⚠️ Authorized Testing Only: Anansi is designed exclusively for authorized security assessments conducted by qualified professionals. Always obtain explicit written permission before testing any system or network you do not own. Unauthorized access is illegal and unethical.

Why I Built It

Every penetration tester knows the pattern. An engagement starts, and within an hour you have fifteen terminal tabs open — nmap running a full port scan, a browser tab open to the NVD for CVE lookups, a cloud enumeration script churning in another window, findings being pasted into a Markdown file by hand. Each tool is excellent at its job, but the workflow between them is held together with shell pipes and hope.

I wanted something better. Not a silver bullet — those don’t exist in security — but a unified environment where the output of one phase feeds naturally into the next. A framework that doesn’t replace individual tools but orchestrates them under a consistent interface, remembers what it found, and surfaces context where it matters.

That’s Anansi.

Design Philosophy

Modularity as a First Principle

The core idea is straightforward: every capability is a plugin. The framework discovers modules at runtime, loads them by category, and exposes them through a consistent CLI interface. Want to add a new cloud provider scanner? Write a module that implements a simple interface, drop it in the right directory, and it appears in the command tree.

This isn’t novel — Metasploit did it first, and frameworks like recon-ng do it well. But most modular frameworks lock you into their ecosystem. Anansi modules are just Python. They receive a target context and return structured findings. No DSL to learn, no custom data format. If you can write a Python function, you can extend it.

This design choice has a practical consequence: modules become composable. The DNS enumeration module doesn’t call nmap directly — it writes findings to a shared context. The CVE correlator reads from that same context and matches services against known vulnerabilities. The report generator consumes everything and produces a formatted output. Each piece works independently, but together they form a pipeline.

Why AI Analysis Made Sense

Adding LLM integration to a security tool is a polarizing decision. I get the skepticism. The last thing anyone needs is a model hallucinating vulnerability findings.

The key is where the AI sits. Anansi doesn’t use AI to discover vulnerabilities — it uses it to summarize and prioritize what was already found by deterministic modules. The LLM receives structured findings (open ports, identified services, matched CVEs, misconfigurations) and produces a plain-language assessment summary with severity rankings and remediation suggestions. The raw data is always available; the AI layer is a convenience, not a source of truth.

I also made the backend fully pluggable. Point it at a local Ollama instance for air-gapped engagements, or use OpenAI/Anthropic when connectivity is available. The framework doesn’t care.

The Dashboard Question

The web dashboard started as an experiment. Most pentest work happens in the terminal, and I strongly believe the CLI should always be the primary interface. But during long-running assessments — think a week-long external pentest with continuous monitoring — having a browser tab open showing real-time progress turned out to be genuinely useful.

The dashboard is optional. If you pip install anansi[dashboard], you get a Flask app with WebSocket updates. If you don’t, nothing changes. The CLI remains the default, the dashboard is an adjunct.

A Realistic Engagement Walkthrough

Here’s how Anansi fits into an actual authorized assessment. I’ll keep this high-level and omit specifics — the goal is to illustrate the workflow, not teach exploitation.

Phase 1: Reconnaissance

The engagement starts with scope definition. A single command targets the client’s CIDR ranges and domain list:

anansi scan --targets scope.txt --modules dns,port,service

This runs three modules in sequence. DNS enumeration resolves subdomains and checks for zone transfers. Port scanning performs a configurable TCP SYN scan across the target ranges. Service fingerprinting identifies versions on open ports.

The output is a structured inventory of hosts, open ports, and identified services, written to a SQLite database.

Phase 2: Vulnerability Correlation

With the inventory populated, the CVE module cross-references each identified service against the NVD API:

anansi analyze --cve --compliance

This fetches relevant CVEs, scores them by severity, and maps findings to controls in common frameworks like NIST SP 800-53 and CIS Benchmarks. The compliance mapping is particularly useful when the engagement requires audit-ready reporting — it saves hours of manual cross-referencing.

Phase 3: Cloud Assessment

If the scope includes cloud infrastructure, dedicated modules evaluate the configuration:

anansi cloud --provider aws --profile engagement

These modules check for common misconfigurations: overly permissive S3 bucket policies, unencrypted storage, exposed IAM credentials, and security group rules that are wider than necessary.

Phase 4: AI-Assisted Review

Before compiling the final report, the AI module summarizes the findings:

anansi report --ai --format markdown

The LLM receives the full finding set and produces an executive summary, a prioritized remediation list, and a technical appendix with references. Every AI-generated statement references the underlying finding ID — nothing is extrapolated from pattern alone.

Phase 5: Deliverable

The final output is a Markdown or HTML report containing the scope summary, methodology, finding details with evidence, risk ratings, compliance mappings, and remediation guidance.

Lessons Learned

The hardest part was dependency management. Python security tools have a notorious dependency conflict problem. Scapy wants one version of libpcap, python-nmap wants another, and cloud SDKs pull in half of PyPI. I solved this by keeping core dependencies minimal and isolating heavy modules behind optional extras (anansi[cloud], anansi[ai], etc.). Docker is the recommended deployment method.

Plugin discovery is deceptively simple. The first iteration used a naive filesystem walker. It worked until modules started having missing dependencies. Now each plugin declares its requirements upfront, and the loader skips modules with unmet dependencies instead of crashing.

CLI ergonomics matter more than I expected. Early versions had verbose, positional-heavy argument structures. After dogfooding a few engagements, I redesigned the CLI around subcommands with sensible defaults. anansi scan should work with zero additional arguments if you’ve configured a scope file.

What’s Next

The immediate roadmap includes:

  • Collaborative mode: multiple operators sharing findings from a central database during team engagements
  • More cloud providers: GCP and Azure assessment modules
  • Report templates: customizable reporting output for different standards (PTES, OWASP, OSSTMM)
  • Jupyter integration: interactive exploration of findings during analysis

Get Involved

Anansi is open source, licensed under MIT. The code is at github.com/herson/anansi. If you do security assessments and have thoughts on what a framework like this should or shouldn’t do, I’d love to hear them. Open an issue, send a pull request, or find me on X.

Whether Anansi fits your workflow or not, the goal remains the same: make it easier to do thorough, well-documented, authorized security work. Everything else is secondary.