Nara

NARA is an autonomous, multi-agent red team CLI. You point it at a open-source repo, and it automatically scans for vulnerabilities, designs an attack chain, and executes it live in a container.

Comment

Inspiration

Every cybersecurity course teaches you what vulnerabilities look like — but almost none show you what actually happens when they get exploited. Tools like Semgrep and Bandit are great at finding problems, but they hand you a list and leave the rest to imagination.

We wanted to close that gap. What if a tool could not only find the vulnerabilities, but show you — in real time, end to end — exactly what an attacker would do with them? That question became NARA.

We were also inspired by the real-world red team / blue team dynamic. Red teams break things. Blue teams fix them. Most tools only do one. We wanted to build a platform that does both: autonomously attack a target, then turn around and advise on how to defend it.

What it does

NARA is an autonomous penetration testing CLI that orchestrates three AI agents against an isolated Docker target:

  • Scanner — runs Semgrep and Bandit against a codebase (local path or GitHub URL), then uses an LLM to deduplicate and prioritize findings by severity and exploitability.
  • Planner — takes those findings and designs an ordered kill chain mapped to MITRE ATT&CK tactics, always culminating in ransomware deployment as the final stage.
  • Exploiter — provisions a disposable Docker container running Ubuntu 22.04 with an XFCE desktop, then executes each kill chain step live. The LLM watches every result and adapts in real time — retrying, rewriting, or aborting steps as needed.
  • Blue Team Advisor — after exploitation, feeds the findings and kill chain to TerpAI (UMD's AI platform) and streams back detailed remediation advice: risk explanations, code-level fixes, detection strategies, and hardening recommendations for every vulnerability found.

The entire attack plays out visually on a live noVNC desktop in your browser. Ransom notes drop, files get encrypted, wallpapers get hijacked — all in a fully sandboxed environment you can reset with one command.

How we built it

The system is built around a shared session dictionary that flows through each agent in sequence, with every agent reading its inputs and writing its outputs back to the same state object.

Agent layer — each agent (scanner.py, planner.py, exploiter.py, blue_team.py) has a single run() entry point and is completely decoupled from the others. They communicate only through the session dict.

LLM abstraction — a unified LLMClient supports three backends with zero code changes: Featherless (Phi-4-mini, our default), Claude API, and local Ollama. Swapping backends is a single .env change.

TerpAI integration — we reverse-engineered TerpAI's internal API by inspecting network requests in DevTools, discovering it uses Server-Sent Events with base64-encoded token chunks. The blue team agent streams the response in real time using requests with stream=True.

Infrastructure — the target runs in a Docker container with Ubuntu 22.04, XFCE desktop, TigerVNC, and noVNC. The Exploiter provisions it at runtime, clones the vulnerable app inside the container, and executes the kill chain via docker exec.

CLI — a full interactive REPL built with prompt_toolkit and Rich, with an intent router that lets you run commands or just talk naturally about your session.

Challenges we ran into

LLM output reliability — getting the Planner to consistently return valid, executable shell commands (not pseudocode or placeholders) required significant prompt engineering and a robust JSON parser that handles markdown fences, think blocks, and wrapped objects.

SSE discovery — we initially assumed TerpAI used polling like most chat apps. When we tested our blue team agent, we discovered it was actually streaming Server-Sent Events with base64-encoded payloads. We had to rewrite the entire client from a polling loop to a streaming SSE parser.

Docker networking — getting the exploit payloads to reach the container's internal services, and the ransomware payload to serve correctly from the host, required careful networking configuration between the host and container.

SSL on macOS — Python 3.13 via Homebrew doesn't link to the macOS system keychain, which broke HTTPS requests. We fixed it with certifi and learned more about Python SSL certificate handling than we expected.

Real-time LLM adaptation — making the Exploiter actually respond intelligently to failed steps (rather than blindly continuing) meant carefully structuring the feedback loop between shell output and LLM assessment.

Accomplishments that we're proud of

  • Built a fully functional end-to-end autonomous red team pipeline in 24 hours
  • Discovered and reverse-engineered TerpAI's undocumented internal API entirely through DevTools network inspection
  • Found a real stored XSS vulnerability in TerpAI during testing and responsibly disclosed it to UMD's security team
  • The blue team advisor creates a genuine feedback loop: the same platform that attacks also defends, which is a novel demo
  • The noVNC live demo is genuinely striking — watching ransomware deploy autonomously on a live desktop is a visceral way to communicate why security matters
  • The LLM backend abstraction means the entire system runs free with local Ollama, making it accessible without API keys

What we learned

  • Multi-agent systems need strong contracts between agents — the session dict pattern worked well, but early on we had agents assuming keys that didn't exist yet
  • LLMs are surprisingly good at adapting shell commands when given real error output, but need very precise prompting to stay in scope
  • Reverse engineering an API from DevTools is completely viable and teaches you a lot about how modern web apps work under the hood
  • The line between a useful security research tool and an irresponsible one is mostly about scope and authorization — we spent real time thinking through the ethics of every feature
  • Responsible disclosure is the right call even at a hackathon — reporting the XSS finding felt more valuable than exploiting it

What's next for Nara

  • Authenticated scanning — extend the scanner to test APIs and authenticated endpoints, not just static code
  • More payload types — data exfiltration simulation, lateral movement, privilege escalation chains
  • Report export — generate a full PDF pentest report with executive summary, technical findings, and remediation roadmap
  • Plugin architecture — let teams add custom exploit modules and payload types without modifying core agents
  • CI/CD integration — run NARA as part of a pull request pipeline to catch vulnerabilities before they ship
  • Blue team agent expansion — deeper TerpAI integration with follow-up questions, patch verification, and compliance mapping (OWASP, NIST)

Built With

Share this project:

Updates