Metadata-Version: 2.4
Name: helios-security
Version: 0.1.1
Summary: AI-powered security agent that autonomously finds, exploits, and fixes vulnerabilities
Author: Nakai Williams
License-Expression: MIT
Project-URL: Repository, https://gitlab.com/nakaiwilliams20/helios
Project-URL: Homepage, https://gitlab.com/gitlab-ai-hackathon/participants/35626002
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: claude-agent-sdk>=0.1.0
Requires-Dist: python-gitlab>=4.0.0
Requires-Dist: click>=8.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: docker>=7.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: flask>=3.0.0
Dynamic: license-file

# 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](https://github.com/anthropics/claude-agent-sdk) for the [GitLab AI Hackathon](https://about.gitlab.com/blog/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

```bash
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](https://github.com/anthropics/claude-agent-sdk) (Python) | AI reasoning engine and MCP tool orchestration |
| Docker | Sandboxed exploitation environment |
| [python-gitlab](https://python-gitlab.readthedocs.io/) | GitLab API integration (issues, MRs, cloning) |
| [Rich](https://github.com/Textualize/rich) | Terminal UI and split-panel arena display |
| [Click](https://click.palletsprojects.com/) | CLI framework |
| [anyio](https://anyio.readthedocs.io/) | 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](LICENSE) for details.

---

## Contributing

Contributions are welcome. To get started:

```bash
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](https://gitlab.com/nakaiwilliams20/helios)
