ExaAiAgent

Advanced AI-Powered Cybersecurity Agent for Comprehensive Penetration Testing

🔥 What's New in v2.3.2

• K8s Scanner Tool Registration: Fixed proper tool invocation flow for Kubernetes scanners (ensuring sandbox execution bypass requirements are strictly met).
• Data Persistence: Accurately saves chat_messages.json, run_metadata.json, agents.json, and tool_executions.json inside the exaai_runs/<run-name> directory.
• Improved Code Quality: Consistent formatting and rigorous linting across the codebase, eliminating missing/mutable-default variables and improving logging.
• SKILL.md Revisions: Extensively updated onboarding procedures to accurately convey configuration overrides for LiteLLM dependencies.

🔥 What's New in v2.2.5

🧱 Runtime Reliability & Developer Workflow

This release focuses on making ExaAiAgent much more predictable to operate and easier to integrate into agent-driven workflows:

• CI on Pull Requests: lint, type-check, unit tests, and smoke tests now run automatically
• Legacy Cleanup: removed stale strix references that broke tests and dev tooling
• Import-Safe Tool Server: sandbox tool server no longer parses CLI arguments at import time
• Dependency Compatibility Fixes: resolved websockets compatibility issues affecting installs

🧠 Better Agent Orchestration

• Improved Agent Messaging: fixed agent resume/waiting behavior and sandbox readiness issues
• Normalized Agent Statuses: cleaner status flow across graph, tracer, and UI
• Multi-Tool LLM Responses: no longer truncates model output to the first tool call only
• Prompt Module Merging: role defaults and user-selected modules now combine correctly

💻 Better CLI/TUI Behavior

• Interactive Target Submission: TUI can now queue a target and start scanning more cleanly
• Improved Error Surfacing: clearer runtime errors in CLI/TUI instead of silent failures
• Smarter Prompt Resolution: auto-detected prompt modules now wire into execution more reliably
• Docker Requirement Made Explicit: first-run/runtime expectations are clearer during startup

🤖 AI Agent Integration

• Repository Skill Updated: SKILL.md now cleanly onboards other AI agents to use and operate ExaAiAgent
• OpenClaw-Friendly Operation: better fit for external AI agents controlling scans or maintaining the tool

🛡️ Smart Security Tools

⚡ CLI & Stability

• Thread-Safety: Fixed race conditions in async scans
• Resource Management: Auto-shutdown and cleanup of background processes
• Installation: Robust install.sh for Linux/macOS (bash/zsh/fish)

# New install script
curl -sSL https://raw.githubusercontent.com/hleliofficiel/ExaAiAgent/main/install.sh | bash

🔥 ExaAiAgent Overview

ExaAiAgent is an elite AI-powered cybersecurity agent that acts like a real penetration tester - running your code dynamically, finding vulnerabilities, and validating them through actual proof-of-concepts. Built for developers and security teams who need fast, accurate security testing.

Key Capabilities:

• 🔧 Full hacker toolkit out of the box
• 🤝 Teams of agents that collaborate and scale
• ✅ Real validation with PoCs, not false positives
• 💻 Developer‑first CLI with actionable reports
• 🔄 Auto‑fix & reporting to accelerate remediation
• 🧠 Multi-LLM Support - OpenAI, Anthropic, Gemini, local models
• 🌐 Cloud & Container Security testing capabilities
• 🚀 Smart Module Loading - Auto-detects and loads relevant modules

🎯 Use Cases

• Application Security Testing - Detect and validate critical vulnerabilities
• Rapid Penetration Testing - Get pentests done in hours, not weeks
• Bug Bounty Automation - Automate research and generate PoCs
• CI/CD Integration - Block vulnerabilities before production
• API Security Testing - REST, GraphQL, gRPC security analysis
• Cloud Security - AWS, Azure, GCP configuration review

🚀 Quick Start

Prerequisites:

• Docker (running)
• Python 3.12+
• An LLM provider (OpenAI, Anthropic, OpenRouter, Ollama, or any compatible provider)

Installation & First Scan

# Install ExaAiAgent

# Method 1: Automated Script (Recommended)
pip install exaai-agent
# Method 2: pipx
pipx install exaai-agent

# Configure your AI provider (choose one)

# Option 1: OpenAI
export EXAAI_LLM="openai/gpt-5"
export LLM_API_KEY="your-openai-key"

# Option 2: Anthropic
export EXAAI_LLM="anthropic/claude-sonnet-4-5"
export LLM_API_KEY="your-anthropic-key"

# Option 3: OpenRouter (access multiple models)
export EXAAI_LLM="openIntelligence
export LLM_API_KEY="your-openrouter-key"
export LLM_API_BASE="https://openrouter.ai/api/v1"

# Option 4: Ollama (local models)
export EXAAI_LLM="ollama/llama3"
export LLM_API_BASE="http://localhost:11434"

# Run your first security assessment (auto-detects modules!)
exaai --target https://your-app.com

✨ Features

🛠️ Agentic Security Tools

ExaAiAgent agents come equipped with a comprehensive security testing toolkit:

• Full HTTP Proxy - Request/response manipulation and analysis
• Browser Automation - Multi-tab browser for XSS, CSRF, auth flows
• Terminal Environments - Interactive shells for command execution
• Python Runtime - Custom exploit development and validation
• Reconnaissance - Automated OSINT and attack surface mapping
• Code Analysis - Static and dynamic analysis capabilities
• API Fuzzing - Advanced REST/GraphQL API testing

🎯 Comprehensive Vulnerability Detection

ExaAiAgent identifies and validates a wide range of security vulnerabilities:

🕸️ Graph of Agents

Advanced multi-agent orchestration for comprehensive security testing:

• Distributed Workflows - Specialized agents for different attacks
• Scalable Testing - Parallel execution for fast coverage
• Dynamic Coordination - Agents collaborate and share discoveries

💻 Usage Examples

Basic Usage

# Scan a local codebase
exaai --target ./app-directory

# Security review of a GitHub repository
exaai --target https://github.com/org/repo

# Black-box web application assessment
exaai --target https://your-app.com

Smart Auto-Loading (New in v2.0!)

# GraphQL endpoint - auto-loads graphql_security
exaai --target https://api.example.com/graphql

# WebSocket - auto-loads websocket_security
exaai --target wss://chat.example.com/socket

# OAuth endpoint - auto-loads oauth_oidc
exaai --target https://auth.example.com/oauth/authorize

# Subdomain recon - auto-loads subdomain_takeover
exaai --target example.com --instruction "enumerate subdomains"

Advanced Testing Scenarios

# Grey-box authenticated testing
exaai --target https://your-app.com --instruction "Perform authenticated testing using credentials: user:pass"

# Multi-target testing (source code + deployed app)
exaai -t https://github.com/org/app -t https://your-app.com

# With specific modules (overrides auto-detection)
exaai --target https://api.example.com --prompt-modules graphql_security,waf_bypass

# Lightweight mode (reduced token consumption)
export EXAAI_LIGHTWEIGHT_MODE=true
exaai --target https://example.com --instruction "quick security scan"

🤖 Headless Mode

Run ExaAiAgent programmatically without interactive UI:

exaai -n --target https://your-app.com

🔄 CI/CD (GitHub Actions)

name: exaai-security-test

on:
  pull_request:

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install ExaAiAgent
        run: curl -sSL https://raw.githubusercontent.com/hleliofficiel/ExaAiAgent/main/install.sh | bash

      - name: Run ExaAiAgent
        env:
          EXAAI_LLM: ${{ secrets.EXAAI_LLM }}
          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
        run: exaai -n -t ./

⚙️ Configuration

# Required
export EXAAI_LLM="openai/gpt-5"
export LLM_API_KEY="your-api-key"

# Optional - Performance tuning
export EXAAI_LIGHTWEIGHT_MODE=true    # Reduced token consumption
export EXAAI_MAX_TOKENS=2048          # Max output tokens
export LLM_API_BASE="your-api-base"   # For local models
export PERPLEXITY_API_KEY="key"       # For search capabilities

Recommended Models:

• OpenAI GPT-5 (openai/gpt-5)
• Anthropic Claude Sonnet 4.5 (anthropic/claude-sonnet-4-5)
• Google Gemini 3.0 (gemini/gemini-2.0-flash)

📦 Available Security Modules

Vulnerability Modules

🆕 Changelog

v2.3.2

Release Overview

Version v2.3.2 is a production-ready maintenance and improvement release focused on stability, reliability, code quality, documentation, and developer experience. Existing functionality has been preserved while introducing meaningful improvements across the project.

✨ What's New

🤖 Agent Improvements

• Improved agent coordination and internal workflow.
• Enhanced reliability during agent execution.
• Better error handling and recovery mechanisms.
• Performance optimizations for smoother execution.
• Internal architecture refactoring to improve maintainability.

☸️ Kubernetes Scanner Improvements

• Fixed Kubernetes tool registration.
• Corrected @register_tool decorators by enabling proper registration with:
  • sandbox_execution=False
• Fixed missing tool argument schemas that previously appeared as None.
• Improved compatibility with the ExaAiAgent tool system.

🖥️ CLI Improvements

• Updated CLI version to v2.3.2.
• Restored headless (non-TTY) output behavior after review.
• Preserved compatibility with:
  • CI pipelines
  • Automation scripts
  • Remote execution
  • Existing command-line workflows

📚 Documentation

SKILL.md

The documentation has been significantly expanded with:

• Installation guide
• Project architecture overview
• Agent workflow explanation
• Usage examples
• Configuration details
• Diagnostic and troubleshooting guide
• Testing instructions using Poetry
• Kubernetes Scanner documentation
• Best practices
• New v2.3.2 capabilities

🔧 Refactoring

• Improved overall code readability.
• Simplified internal implementation where appropriate.
• Removed unnecessary complexity.
• Improved maintainability while keeping backward compatibility.

🐞 Bug Fixes

• Fixed Kubernetes tool registration issues.
• Fixed missing tool argument metadata.
• Restored CLI output for non-interactive environments.
• Fixed minor inconsistencies discovered during review.

✅ Quality Assurance

Before release:

• All tests executed successfully.
• Build verification completed.
• No linting issues remaining.
• Regression review completed.
• Existing functionality verified.
• New features capabilities.
• Codebase reviewed for unintended side effects.

Result: 89/89 tests passed successfully.

Backward Compatibility

This release maintains backward compatibility wherever possible.

No breaking API or workflow changes were intentionally introduced.

Existing automation, scripts, and CI environments continue to work as expected.

Release Summary

ExaAiAgent v2.3.2 focuses on delivering a stable production release with improved agent reliability, Kubernetes scanning enhancements, restored CLI compatibility, expanded documentation, codebase refactoring, and comprehensive testing, while maintaining full backward compatibility.

v2.2.5 (Latest)

• Runtime Reliability: fixed interactive scan flow, tool-server import safety, sandbox readiness, and agent messaging issues
• Developer Workflow: CI now runs lint, type-check, tests, and smoke checks on pull requests
• Prompt Intelligence: smarter prompt resolution, merged default/user modules, and new specialist prompt modules for planning, validation, reporting, and runtime recovery
• Agent Coordination: normalized statuses and improved multi-tool execution behavior
• Agent Onboarding: refreshed SKILL.md so external AI agents can operate and maintain ExaAiAgent more reliably

v2.2.2

• Reconnaissance Engine: New modules for subdomain enumeration, port scanning, and tech fingerprinting
• AI Agent Integration: OpenClaw/Agent compatibility
• Stability Fixes: ToolManager thread-safety, Resource cleanup
• DevEx: New install.sh script, improved logging

v2.1.2

• Bugfix: Fixed k8s scanner import issue
• Banner: Updated banner version string

v2.1.0

• New Modules: K8s, Azure, GCP, Prompt Injection
• React2Shell: CVE-2025-55182 detection
• Auto-Discovery: Improved target detection

🛠️ Troubleshooting

🔧 Troubleshooting

Problem: "LLM Connection Failed" or Model Not Found

Modern models (like gemini-3-pro-preview) require the latest version of litellm to be recognized correctly.

Solution: Update LiteLLM

pip install -U litellm

Linux/Debian Users (Externally Managed Environment): If you encounter permission errors or "externally-managed-environment", you may need to use a virtual environment (venv) or force a user install:

# Option 1: Virtual Environment (Recommended for Servers)
python3 -m venv venv
source venv/bin/activate
pip install exaai-agent

# Option 2: Force User Install
pip install -U litellm --user --break-system-packages

🤝 Contributing

We welcome contributions! Check out our Contributing Guide.

🌟 Support the Project

Love ExaAiAgent? Give us a ⭐ on GitHub!

🙏 Acknowledgements

ExaAiAgent builds on incredible open-source projects like LiteLLM, Caido, ProjectDiscovery, Playwright, and Textual.