helios-security 0.1.0

AI-powered security agent that autonomously finds, exploits, and fixes vulnerabilities

Helios

Your code has secrets. Helios finds them.

Helios is an AI-powered security agent that autonomously finds, exploits, and fixes vulnerabilities in codebases. It features the world's first Adversarial Agents Arena -- where an AI attacker and an AI defender battle in real-time over your code's security.

Built with the Claude Agent SDK for the GitLab AI Hackathon.

---

What Makes Helios Different

Most security tools scan for patterns. Helios thinks like a hacker.

Feature	Traditional Scanners	Helios
Detection	Pattern matching	AI-powered contextual code analysis
Verification	"You might be vulnerable"	"I just exploited this. Here's the proof."
Exploitation	None	Sandbox exploitation with proof-of-concept
Defense Testing	None	AI vs AI adversarial battle
Supply Chain	Single repo	Cross-repository attack surface analysis
Custom Exploits	Predefined payloads	AI generates bespoke exploits per vulnerability
Cost	$15-50K/pentest or $/scan	Your existing Claude subscription

---

Features

Adversarial Agents Arena

Two Claude Agent SDK instances battle in real-time. Red Agent attacks. Blue Agent defends. You watch.

• Swarm mode: multiple Red Agents coordinate simultaneous attacks (--attackers 3)
• Red Agent writes custom exploit scripts on the fly, chains vulnerabilities, and adapts when blocked
• Blue Agent monitors logs, patches vulnerabilities in a live container, and deploys WAF rules
• Live split-panel terminal display with real-time scoring via Rich

Autonomous Vulnerability Scanner

• Static analysis: SQL injection, XSS, command injection, SSRF, path traversal
• Secret detection: API keys, passwords, tokens, private keys
• Dependency vulnerability checking
• Configuration audit: Docker misconfigurations, CORS, debug mode

Sandbox Exploitation Engine

• Docker-based sandboxed environment for safe, real exploitation
• Actual proof-of-concept exploits -- not theoretical findings
• SQL injection auth bypass, reflected XSS, SSRF, path traversal, command injection
• AI-generated custom payloads tailored to the specific codebase

Supply Chain Attack Surface Analysis

• Cross-repository dependency mapping
• Transitive vulnerability detection
• Identifies how vulnerabilities in package A create attack vectors in package B

GitLab Native Integration

• Clone repositories via GitLab API
• Create issues with severity labels, exploitation proof, and fix recommendations
• Open fix branches and merge requests automatically
• Drop-in CI/CD pipeline template for any repository

---

Quick Start

pip install helios-security

# Scan a local codebase
helios scan ./my-app

# Scan with exploit verification in Docker sandbox
helios scan ./my-app --exploit

# Run the Adversarial Agents Arena
helios arena-demo --intensity medium

# Swarm mode: 2 attackers vs 1 defender
helios arena-demo --intensity high --attackers 2

# Supply chain analysis across multiple repos
helios supply-chain ./app-repo ./dependency-repo

# Full attack pipeline against a GitLab repo
helios attack https://gitlab.com/org/repo --fix --create-mr

# Set up GitLab CI/CD
helios ci-setup

Requirements

• Python 3.10+
• Docker (for sandbox exploitation and arena mode)
• Claude subscription (for AI-powered analysis and arena agents)
• GitLab personal access token (optional, for GitLab integration)

---

Architecture

Claude Agent SDK
  |
  +-- Red Agent (attacker)
  |     +-- Scanner (static analysis, secrets, deps, config audit)
  |     +-- Exploiter (SQLi, XSS, SSRF, auth bypass, path traversal)
  |     +-- Custom Exploit Generator (AI writes bespoke attack scripts)
  |     +-- Supply Chain Analyzer (cross-repo transitive vectors)
  |
  +-- Blue Agent (defender)
  |     +-- Log Monitor (real-time container log analysis)
  |     +-- Patch Deployer (live patching of running containers)
  |     +-- WAF Rule Engine (runtime input validation)
  |     +-- Patch Verifier (confirms fixes block attack vectors)
  |
  +-- Arena Orchestrator
        +-- Docker Sandbox (isolated exploitation environment)
        +-- Score Tracker (Red exploits vs Blue patches)
        +-- Rich Terminal Display (split-panel live output)

---

CLI Commands

Command	Description
helios scan <target>	Scan a codebase or GitLab URL for vulnerabilities
helios attack <target>	Full pipeline: scan, exploit, fix, and create merge requests
helios arena <target>	Launch the Adversarial Agents Arena against your codebase
helios arena-demo	Run the arena against the built-in vulnerable Flask app
helios supply-chain <repos...>	Analyze supply chain attack surface across multiple repos
helios report <target>	Generate Markdown and JSON security reports
helios demo	Scan the built-in vulnerable demo app
helios ci-setup	Install the GitLab CI/CD pipeline template

All commands support --help for full option details.

---

Real-World Results

Tested against real GitLab-hosted projects:

Target	Vulnerabilities	Critical	Exploited in Sandbox
Inkscape Web (GitLab-hosted)	19	3	Yes

• Supply chain: 62 transitive attack vectors identified between Inkscape Web and django-cms dependency trees
• Arena (swarm mode): Red Agent 14 vs Blue Agent 8 -- Red Agent wins with exploit chaining
• All exploits verified with proof-of-concept output captured in Docker sandbox

---

How It Works

1. Claude Agent SDK with custom MCP tools -- Red and Blue agents each receive a tailored set of security tools (scanner, exploiter, patcher, WAF) exposed via the Model Context Protocol. The agents reason about which tools to invoke and in what order.

2. Docker sandbox for safe exploitation -- A containerized copy of the target application runs in isolation. Exploits execute against the live container, producing real proof (HTTP responses, database dumps, file contents) without touching production systems.

3. Concurrent adversarial agents via anyio task groups -- Red and Blue agents run simultaneously in the same event loop. Red attacks while Blue monitors, detects, and patches in real-time. In swarm mode, multiple Red Agent instances coordinate attacks concurrently.

4. Rich terminal display -- A split-panel terminal UI streams Red and Blue agent actions side-by-side with live scoring, using the Rich library for formatted output.

---

Tech Stack

Component	Role
Claude Agent SDK (Python)	AI reasoning engine and MCP tool orchestration
Docker	Sandboxed exploitation environment
python-gitlab	GitLab API integration (issues, MRs, cloning)
Rich	Terminal UI and split-panel arena display
Click	CLI framework
anyio	Async concurrency for parallel agents

---

Why Helios

1. Deep Claude Agent SDK integration -- Custom MCP tools for scanning, exploitation, patching, and WAF deployment. Not a wrapper around an API call; the agents reason, adapt, and chain tools autonomously.

2. First-ever adversarial AI agents for security -- Two Claude instances with opposing objectives battle over the same codebase in real-time. Red Agent writes custom exploit scripts. Blue Agent patches live containers.

3. AI generates custom exploits -- Not predefined payloads. The Red Agent analyzes the specific codebase, crafts bespoke attack scripts, and adapts when defenses change.

4. Real exploitation with proof -- Every finding is verified in a Docker sandbox with captured output. No false positives, no theoretical warnings.

5. Zero additional cost -- Runs on your existing Claude subscription. No per-scan fees, no enterprise pricing.

6. Supply chain attack surface analysis -- Maps transitive vulnerabilities across repository boundaries. "This XSS in your dependency creates an auth bypass in your app."

7. GitLab-native -- Clone repos, create severity-labeled issues, open fix merge requests, and drop a CI/CD template into any project.

8. Open source -- MIT licensed. Use it, extend it, contribute to it.

---

License

MIT -- see LICENSE for details.

---

Contributing

Contributions are welcome. To get started:

git clone https://gitlab.com/nakaiwilliams20/helios.git
cd helios
pip install -e ".[dev]"

Please open an issue before submitting large changes. All contributions must include tests where applicable and follow the existing code style.

---

Repository: gitlab.com/nakaiwilliams20/helios