https://github.com/arn-c0de/peterpentest

AI-powered autonomous penetration testing framework with local LLM, RAG memory, automated vulnerability analysis, and secure workflow orchestration.
https://github.com/arn-c0de/peterpentest

ai automation cyber-security ethical-hacking nmap ollama penetration-testing python rag redteam security sqlite ssh vulnerability-scanner workflow

Last synced: 3 months ago
JSON representation

AI-powered autonomous penetration testing framework with local LLM, RAG memory, automated vulnerability analysis, and secure workflow orchestration.

Host: GitHub
URL: https://github.com/arn-c0de/peterpentest
Owner: arn-c0de
License: other
Created: 2025-11-08T00:14:53.000Z (3 months ago)
Default Branch: v1.0.3
Last Pushed: 2025-11-08T13:58:37.000Z (3 months ago)
Last Synced: 2025-11-08T14:35:38.171Z (3 months ago)
Topics: ai, automation, cyber-security, ethical-hacking, nmap, ollama, penetration-testing, python, rag, redteam, security, sqlite, ssh, vulnerability-scanner, workflow
Language: Python
Homepage:
Size: 2.25 MB
Stars: 1
Watchers: 0
Forks: 0
Open Issues: 1
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md

Awesome Lists containing this project

README

          






  



PeterPentest - AI-Powered Penetration Testing Framework

Autonomous penetration testing framework using local Ollama LLM with RAG memory and automated vulnerability analysis.

[![License: Non-Commercial](https://img.shields.io/badge/License-Non--Commercial-red.svg)](./LICENSE)

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

[![Version](https://img.shields.io/badge/version-1.0.3-green.svg)](./CHANGELOG.md)

[![Development Status](https://img.shields.io/badge/status-early--development-orange.svg)]()

[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/arn-c0de/PeterPentest)

> **⚠️ EARLY DEVELOPMENT NOTICE**  

> This project is in a **very early stage of development** and is currently **NOT ready for production use**.  

> It is intended for **development and testing purposes only**.  

> Features may be incomplete, unstable, or subject to significant changes.  

> Use at your own risk.

## � Features

- **AI-Driven Decision Making**: Local Ollama LLM (`qwen3:8b`) for intelligent penetration testing

- **RAG System**: ChromaDB vector database with 119 pentesting documents

- **Persistent Memory**: SQLite storage for conversations, tasks, and findings

- **9 Automation Tools**: LinEnum, LinPEAS, WinPEAS, pspy, PowerUp, LSE, Exploit Suggester, SearchSploit, Nmap

- **5 Pre-built Workflows**: Full enumeration, privilege escalation, vulnerability scanning

- **SSH Integration**: Remote command execution and system enumeration

- **Network Scanning**: Nmap integration with AI analysis

- **Automated Reports**: Markdown/HTML/PDF report generation

## 📋 Quick Links

- **[Documentation](./docs/README.md)** - Complete documentation hub

- **[Getting Started](./docs/user-guide/GETTING_STARTED.md)** - Quick start guide

- **[CLI Reference](./docs/user-guide/CLI_REFERENCE.md)** - Command reference

- **[Configuration](./docs/user-guide/CONFIGURATION.md)** - Settings and optimization

- **[Troubleshooting](./docs/user-guide/TROUBLESHOOTING.md)** - Common issues

- **[Contributing](./CONTRIBUTING.md)** - Contribution guidelines

- **[Security](./SECURITY.md)** - Security policy

- **[Changelog](./CHANGELOG.md)** - Version history

## 🎯 Quick Start

### Requirements

- **Python 3.10+**

- **Ollama** with `qwen3:8b` model

- **16GB RAM** recommended (8GB minimum)

- **GPU** (RTX 3060+) recommended for best performance

### Installation

**Windows:**

```bash

git clone https://github.com/arn-c0de/PeterPentest.git

cd PeterPentest

setup.bat

```

**Linux:**

```bash

git clone https://github.com/arn-c0de/PeterPentest.git

cd PeterPentest

chmod +x setup.sh

./setup.sh

```

### First Run

```bash

# Initialize system

python main.py init

# Check status

python main.py status

# Start chat mode

python main.py

```

## 💡 Usage Examples

### Interactive Chat

```bash

python main.py chat

You: wie ist meine IP?

AI: [executes get_network_info]

    Hostname: DESKTOP-XYZ | Primary IPv4: 192.168.1.100 | Primary IPv6: 2a02:...

You: scanne meine IP

AI: [automatically uses 192.168.1.100 from context]

```

**Chat Commands:**

- `/save` - Export session (IPs, hosts, ports, findings)

- `/load ` - Import previous session context

- `/stats` - Show session statistics

- `/tools` - List available tools

- `/help` - Show all commands

### Session Management

```bash

# Save current session

python main.py chat

You: /save

✓ Session saved to ./reports/default_20251108_143000/

# Load previous session

You: /load ./reports/default_20251108_143000/default_context.json

✓ Loaded: 5 discovered hosts, 23 open ports

# Or use CLI

python main.py export-session --session default --output ./reports

python main.py import-session ./reports/default_context.json --session pentest-2024

```

### Network Scan

```bash

# Quick scan

python main.py scan 192.168.1.0/24 --quick

# Full scan

python main.py scan 192.168.1.100 --full

```

### SSH Enumeration

```bash

python main.py ssh-enum 192.168.1.100 --username admin

```

### List Tools & Workflows

```bash

# Show all tools

python main.py list-tools

# Show workflow details

python main.py workflow-info linux_full_enum

```

## 🛠️ Available Tools

| Tool | Category | Platform | Description |

|------|----------|----------|-------------|

| **LinEnum** | Enumeration | Linux | System enumeration script |

| **LinPEAS** | PrivEsc | Linux | Privilege escalation detector |

| **WinPEAS** | PrivEsc | Windows | Windows privilege escalation |

| **pspy** | Enumeration | Linux | Process monitoring without root |

| **PowerUp** | PrivEsc | Windows | PowerShell privilege checks |

| **LSE** | Enumeration | Linux | Smart Linux enumeration |

| **Exploit Suggester** | VulnScan | Linux | Kernel exploit finder |

| **SearchSploit** | VulnScan | Any | Exploit database search |

| **Nmap Vuln Scan** | VulnScan | Any | Network vulnerability scanning |

## 🔄 Workflows

| Workflow | Platform | Steps | Duration | Description |

|----------|----------|-------|----------|-------------|

| **linux_full_enum** | Linux | 5 | 8-12 min | Complete system enumeration |

| **windows_full_enum** | Windows | 3 | 10-15 min | Windows enumeration |

| **quick_enum** | Any | 2 | 1-2 min | Fast reconnaissance |

| **privesc_check** | Linux | 5 | 5-8 min | Privilege escalation vectors |

| **vuln_scan** | Any | 3 | 15-30 min | Vulnerability scanning |

## ⚙️ Configuration

Edit `config/settings.yaml`:

```yaml

ollama:

  model: qwen3:8b

  context_window: 14000  # RTX 3080 optimized

  max_tokens: 4096

rag:

  top_k: 10  # Knowledge base results

  

memory:

  conversation_limit: 50  # Recent messages

```

**Hardware Optimization:**

- **RTX 3080**: `context_window: 14000`

- **RTX 3060**: `context_window: 8192`

- **CPU only**: `context_window: 4096`

See [Configuration Guide](./docs/user-guide/CONFIGURATION.md) for details.

## 📊 System Architecture

```

┌─────────────────────────────────────────────────────┐

│                   CLI Interface                     │

└────────────────────┬────────────────────────────────┘

                     │

┌────────────────────▼────────────────────────────────┐

│                  Orchestrator                       │

│  ┌──────────┬──────────┬──────────┬──────────────┐  │

│  │ AI Engine│ RAG      │ Memory   │ Automation   │  │

│  │ (LLM)    │ System   │ System   │ Tools        │  │

│  └──────────┴──────────┴──────────┴──────────────┘  │

└────────────────────┬────────────────────────────────┘

                     │

        ┌────────────┴────────────┐

        │                         │

┌───────▼─────────┐    ┌──────────▼──────────┐

│ Ollama (qwen3)  │    │ Modules (SSH, Scan) │

└─────────────────┘    └─────────────────────┘

```

## 🔒 Security & Legal

**⚠️ IMPORTANT**: Only use on systems you have **written authorization** to test.

- Unauthorized access is **illegal**

- All actions are **logged** for audit

- Safe mode prevents destructive actions

- See [SECURITY.md](./SECURITY.md) for full policy

## Support

- **Issues**: [GitHub Issues](https://github.com/arn-c0de/PeterPentest/issues)

- **Discussions**: [GitHub Discussions](https://github.com/arn-c0de/PeterPentest/discussions)

- **Documentation**: [docs/](./docs/README.md)

- **Email**: arn-c0de@protonmail.com (security issues only)

## 📖 Documentation

Complete documentation in [docs/](./docs/README.md):

- **User Guides** (8 documents)

  - Getting Started, CLI Reference, Configuration, SSH Usage, Workflows, Troubleshooting

- **Features** (2 documents)

  - Automation Tools, GUI Features  

- **Technical** (3 documents)

  - Architecture, Technology Stack, Performance Tuning

- **Development** (3 documents)

  - AI Context, Contributing, Development Setup

**Total**: 16 comprehensive documentation files

## 🤝 Contributing

Contributions welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) before submitting PRs.

**Quick start:**

1. Fork repository

2. Create feature branch: `git checkout -b feature/amazing-feature`

3. Commit changes: `git commit -m 'Add amazing feature'`

4. Push branch: `git push origin feature/amazing-feature`

5. Open Pull Request

## 📝 License

**Non-Commercial License** - see [LICENSE](./LICENSE)

**Key Points:**

- ✅ Free for personal, educational, and research use

- ❌ Commercial use prohibited without permission

- ⚠️ Must obtain authorization before testing any systems

- 📝 Must comply with all applicable laws

- 🔒 Includes warranty disclaimer

- 🚧 Early development - not production ready

## 🙏 Acknowledgments

- **[Ollama](https://ollama.ai)** - Local LLM runtime

- **[ChromaDB](https://www.trychroma.com/)** - Vector database

- **[PEASS-ng](https://github.com/carlospolop/PEASS-ng)** - LinPEAS/WinPEAS

- **[LinEnum](https://github.com/rebootuser/LinEnum)** - Linux enumeration

- **Security Community** - For incredible open-source tools

## 📞 Support

- **Issues**: [GitHub Issues](https://github.com/arn-c0de/PeterPentest/issues)

- **Discussions**: [GitHub Discussions](https://github.com/arn-c0de/PeterPentest/discussions)

- **Documentation**: [docs/](./docs/README.md)

- **Email**: arn-c0de@protonmail.com (security issues only)

## 👨‍💻 Author

**PeterPentest** — AI-Powered Penetration Testing Framework

Maintained by [arn-c0de](https://github.com/arn-c0de)

---

**⚠️ Legal Disclaimer**: This tool is solely for authorized penetration tests and security audits. Unauthorized access to computer systems is illegal. You must have written permission before testing any systems. See [SECURITY.md](./SECURITY.md) and [LICENSE](./LICENSE) for complete terms.

**� Early Development**: This project is in early development and **not production-ready**. Use only for development, testing, and research purposes in controlled environments.

**📜 License**: Non-commercial use only. Commercial use requires explicit permission from the author.

**�🔒 Remember**: With great power comes great responsibility. Use PeterPentest ethically and legally.

```

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/arn-c0de/peterpentest

Awesome Lists containing this project

README

PeterPentest - AI-Powered Penetration Testing Framework