🔐 Guardian

AI-Powered Penetration Testing Automation Platform

Guardian is an enterprise-grade AI-powered penetration testing automation framework that combines the strategic reasoning of Google Gemini with battle-tested security tools to deliver intelligent, adaptive security assessments.

Features • Installation • Quick Start • Documentation • Contributing

Guardian is designed exclusively for authorized security testing and educational purposes.

• ✅ Legal Use: Authorized penetration testing, security research, educational environments
• ❌ Illegal Use: Unauthorized access, malicious activities, any form of cyber attack

You are fully responsible for ensuring you have explicit written permission before testing any system. Unauthorized access to computer systems is illegal under laws including the Computer Fraud and Abuse Act (CFAA), GDPR, and equivalent international legislation.

By using Guardian, you agree to use it only on systems you own or have explicit authorization to test.

• Multi-Agent Architecture: Specialized AI agents (Planner, Tool Selector, Analyst, Reporter) collaborate for comprehensive security assessments
• Strategic Decision Making: Google Gemini analyzes findings and determines optimal next steps
• Adaptive Testing: AI adjusts tactics based on discovered vulnerabilities and system responses
• False Positive Filtering: Intelligent analysis reduces noise and focuses on real vulnerabilities

15 Integrated Security Tools:

• Network: Nmap (comprehensive port scanning), Masscan (ultra-fast scanning)
• Web Reconnaissance: httpx (HTTP probing), WhatWeb (technology fingerprinting), Wafw00f (WAF detection)
• Subdomain Discovery: Subfinder (passive enumeration), Amass (active/passive mapping)
• Vulnerability Scanning: Nuclei (template-based), Nikto (web vulnerabilities), SQLMap (SQL injection), WPScan (WordPress)
• SSL/TLS Testing: TestSSL (cipher analysis), SSLyze (advanced configuration analysis)
• Content Discovery: Gobuster (directory brute forcing), FFuf (advanced web fuzzing)

• Scope Validation: Automatic blacklisting of private networks and unauthorized targets
• Audit Logging: Complete transparency with detailed logs of all AI decisions and actions
• Human-in-the-Loop: Configurable confirmation prompts for sensitive operations
• Safe Mode: Prevents destructive actions by default

• Multiple Formats: Markdown, HTML, and JSON reports
• Executive Summaries: Non-technical overviews for stakeholders
• Technical Deep-Dives: Detailed findings with evidence and remediation steps
• AI Decision Traces: Full transparency into AI reasoning process

• Asynchronous Execution: Parallel tool execution for faster assessments
• Workflow Automation: Predefined workflows (Recon, Web, Network, Autonomous)
• Customizable: Create custom tools and workflows via simple YAML/Python

• Python 3.11 or higher (Download)
• Google Gemini API Key (Get Free API Key)
• Git (for cloning repository)

Guardian can intelligently use these tools if installed:

Note: Guardian works without external tools but with limited scanning capabilities. The AI will adapt based on available tools.

Easiest and fastest way to get started with all 15 security tools pre-installed!

# Clone repository
git clone https://github.com/zakirkun/guardian-cli.git
cd guardian-cli

# Create .env file with your API key
echo "GOOGLE_API_KEY=your_api_key_here" > .env

# Build Docker image (one-time, ~5 minutes)
docker-compose build

# Run Guardian
docker-compose run --rm guardian recon --domain example.com

Benefits:

• ✅ All 15 tools pre-installed (nmap, httpx, nuclei, sqlmap, etc.)
• ✅ No manual tool installation required
• ✅ Consistent environment across all systems
• ✅ Isolated and secure

See Docker Guide for advanced usage.

git clone https://github.com/zakirkun/guardian-cli.git
cd guardian-cli

Linux/macOS:

python3 -m venv venv
source venv/bin/activate
pip install -e .

Windows:

python -m venv venv
.\venv\Scripts\activate
pip install -e .

# Linux/macOS
python -m cli.main init

# Windows
python -m cli.main init
# or use the batch launcher
.\guardian.bat init

During initialization, you'll be prompted for your Gemini API key. Alternatively, create a .env file:

echo "GOOGLE_API_KEY=your_api_key_here" > .env

# List available workflows
python -m cli.main workflow list

# Dry run (see execution plan without running)
python -m cli.main recon --domain example.com --dry-run

# Fast security check of a web application
python -m cli.main workflow run --name web --target https://example.com

# Full network penetration test
python -m cli.main workflow run --name network --target 192.168.1.0/24

# Discover and analyze subdomains
python -m cli.main recon --domain example.com

# Let AI decide each step dynamically
python -m cli.main workflow run --name autonomous --target example.com

# Create HTML report from previous scan
python -m cli.main report --session 20251222_120000 --format html

# View AI decision-making process
python -m cli.main ai --last

Windows Users: Use python -m cli.main or .\guardian.bat instead of guardian

• Quick Start Guide - Get up and running in 5 minutes
• Docker Deployment Guide - Run Guardian with Docker (recommended)
• Command Reference - Detailed documentation for all commands
• Configuration Guide - Customize Guardian's behavior

• Creating Custom Tools - Build your own tool integrations
• Workflow Development - Create custom testing workflows
• Available Tools - Overview of integrated tools

• Multi-Agent System: Planner → Tool Selector → Analyst → Reporter
• AI-Driven: Google Gemini for strategic decision-making
• Modular: Easy to extend with new tools and workflows

guardian-cli/
├── ai/                    # AI integration (Gemini client, prompts)
├── cli/                   # Command-line interface
│   └── commands/         # CLI commands (init, scan, recon, etc.)
├── core/                  # Core agent system
│   ├── agent.py          # Base agent
│   ├── planner.py        # Planner agent
│   ├── tool_agent.py     # Tool selection agent
│   ├── analyst_agent.py  # Analysis agent
│   ├── reporter_agent.py # Reporting agent
│   ├── memory.py         # State management
│   └── workflow.py       # Workflow orchestration
├── tools/                 # Pentesting tool wrappers
│   ├── nmap.py           # Nmap integration
│   ├── masscan.py        # Masscan integration
│   ├── httpx.py          # httpx integration
│   ├── subfinder.py      # Subfinder integration
│   ├── amass.py          # Amass integration
│   ├── nuclei.py         # Nuclei integration
│   ├── sqlmap.py         # SQLMap integration
│   ├── wpscan.py         # WPScan integration
│   ├── whatweb.py        # WhatWeb integration
│   ├── wafw00f.py        # Wafw00f integration
│   ├── nikto.py          # Nikto integration
│   ├── testssl.py        # TestSSL integration
│   ├── sslyze.py         # SSLyze integration
│   ├── gobuster.py       # Gobuster integration
│   ├── ffuf.py           # FFuf integration
│   └── ...               # 15 tools total
├── workflows/             # Workflow definitions (YAML)
├── utils/                 # Utilities (logging, validation)
├── config/                # Configuration files
├── docs/                  # Documentation
└── reports/               # Generated reports

Edit config/guardian.yaml to customize:

ai:
  provider: gemini
  model: gemini-1.5-pro
  temperature: 0.2

pentest:
  safe_mode: true              # Prevent destructive actions
  require_confirmation: true   # Confirm before each step
  max_parallel_tools: 3        # Concurrent tool execution

scope:
  blacklist:                   # Never scan these
    - 127.0.0.0/8
    - 10.0.0.0/8

We welcome contributions! Here's how:

# Fork and clone
git clone https://github.com/zakirkun/guardian-cli.git
cd guardian-cli

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

# Format code
black .

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

• 🛠️ New Tool Integrations - Add more security tools
• 🔄 Custom Workflows - Share your workflow templates
• 🐛 Bug Fixes - Report and fix issues
• 📚 Documentation - Improve guides and examples
• 🧪 Testing - Expand test coverage

See CONTRIBUTING.md for detailed guidelines.

• Web Dashboard for visualization
• PostgreSQL backend for multi-session tracking
• MITRE ATT&CK mapping for findings
• Plugin system for custom modules
• Integration with CI/CD pipelines
• Additional AI models support (Claude, GPT-4)
• Mobile app for on-the-go assessments

Import Errors

# Reinstall dependencies
pip install -e . --force-reinstall

API Rate Limits

• Free tier: 2 requests/minute
• Switch to paid tier or implement request throttling
• Configure in config/guardian.yaml: ai.rate_limit: 60

Tool Not Found

# Check tool availability
which nmap
which httpx

# Install missing tools (see Prerequisites)

Windows Command Not Found

# Use full command
python -m cli.main --help

# Or use batch launcher
.\guardian.bat --help

For more help, open an issue.

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2025 Guardian Project

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...

• Google Gemini - AI capabilities
• LangChain - AI orchestration framework
• ProjectDiscovery - Open-source security tools (httpx, subfinder, nuclei)
• Nmap - Network exploration and security auditing
• The Security Community - Tool developers and researchers

• GitHub Issues: Report bugs or request features
• Discussions: Join community discussions
• Documentation: Read the docs
• Security: Report vulnerabilities privately to security@example.com

If you find Guardian useful, please consider giving it a star! ⭐