doc.go

/*
Package simple-exploit provides an AI-powered penetration testing framework
with dual AI-engine support: GitHub Models (GPT-4o/GPT-5, cloud) and Ollama
(Gemma4, Llama 3, local/offline).

# Overview

Simple-Exploit is a comprehensive penetration testing framework that combines
artificial intelligence and advanced evasion techniques to identify and exploit
security vulnerabilities in web applications, APIs, Active Directory,
authentication systems, Kubernetes clusters, and LLM / AI APIs.

The framework features an interactive REPL mode with real-time AI assistance,
context-aware vulnerability analysis, and intelligent attack recommendations
based on actual scan results.  The AI engine is runtime-switchable: start with
GitHub Models and switch to a local Ollama/Gemma4 instance (or vice-versa)
without restarting.

# Features

  - Dual AI Engine: GitHub Models (cloud) or Ollama (local) — switchable at runtime
  - Gemma4 / Ollama Support: Run fully offline with gemma4:e4b, llama3.1, deepseek-r1, or any Ollama model
  - OWASP LLM Top 10 (2025): Full active test suite via the llm-attack plugin
  - Context-Aware Intelligence: Analyzes actual scan/attack data instead of generic templates
  - Interactive REPL Mode: Terminal interface with persistent context and AI chat
  - Smart Pattern Recognition: Automatically categorizes endpoints (auth, API, admin, file operations)
  - Runtime Model Switching: model ollama [tag] / model github [model] — no restart needed
  - Automatic Retry: Exponential backoff for rate limiting (2s, 4s, 8s)
  - WAF Bypass Engine: Active fingerprinting and adaptive bypass strategies
  - Interactive Approval: Human-in-the-loop confirmation for attack execution
  - Adaptive Rate Limiting: Token bucket algorithm with circuit breaker pattern

# Installation

Install using go install:

	go install github.com/htunn/simple-exploit/cmd/exploit@latest

Or build from source:

	git clone https://github.com/htunn/simple-exploit.git
	cd simple-exploit
	go build -o exploit cmd/exploit/main.go

# Quick Start

GitHub Models (cloud):

	export GITHUB_TOKEN="github_pat_xxxxxxxxxxxxx"
	./exploit

Ollama / Gemma4 (local, no token needed):

	ollama pull gemma4:e4b
	ollama serve
	export SIMPLE_EXPLOIT_ENGINE=ollama
	./exploit

Inside the REPL:

	🔥 exploit> target https://example.com
	🔥 exploit> model ollama gemma4:e4b    # switch to local Gemma4
	🔥 exploit> model github gpt-4o        # switch back to GitHub Models
	🔥 exploit> scan
	🔥 exploit> scan llm-attack http://localhost:11434   # OWASP LLM Top 10 scan
	🔥 exploit> analyze scan
	🔥 exploit> ask how to bypass cloudflare waf?
	🔥 exploit> attack sqli
	🔥 exploit> help

# OWASP LLM Top 10 (2025)

The llm-attack plugin covers all ten OWASP LLM security risks:

  - LLM01 Prompt Injection: direct, indirect, system-prompt override, Gemma4 thinking-chain injection
  - LLM02 Sensitive Information Disclosure: training-data extraction, credential leak probes
  - LLM03 Supply Chain: model-card tampering detection, poisoned-model repository probes
  - LLM04 Data and Model Poisoning: fine-tune endpoint abuse, poisoned data submission
  - LLM05 Improper Output Handling: XSS via LLM output, code-injection output probes
  - LLM06 Excessive Agency: tool-call abuse, over-permissioned plugin detection
  - LLM07 System Prompt Leakage: direct-ask extraction, inference via output-format manipulation
  - LLM08 Vector and Embedding Weaknesses: unauthenticated vector DB access, embedding inversion
  - LLM09 Misinformation: hallucination confidence probing
  - LLM10 Unbounded Consumption: token flooding, repetitive query DoS, sponge attacks

Supported targets: OpenAI, Anthropic, Ollama, Vertex AI, Hugging Face, RAG pipelines,
Weaviate, Qdrant, Chroma, Pinecone, and Gemma4.

# AI Analysis

The framework provides intelligent analysis based on actual scan and attack results:

Scan Analysis:
  - Attack surface analysis with specific vulnerabilities
  - Technology-specific risks and CVEs
  - Endpoint pattern recognition (auth, API, admin, files)
  - Recommended attack vectors prioritized by findings
  - Step-by-step exploitation roadmap

Attack Analysis:
  - For failures: why it failed, alternative approaches, bypass techniques
  - For successes: impact assessment, exploitation depth, remediation steps
  - Evidence-based recommendations using actual result data

# Architecture

The framework is organized into several key components:

  - Agent Orchestrator: coordinates scanning and exploitation phases; uses the LLMBackend interface
  - GitHub Models Client (internal/copilot): direct API integration with retry logic
  - Ollama Client (internal/ollama): local Ollama API client; satisfies the same LLMBackend interface
  - LLMBackend Interface (internal/copilot): shared contract enabling runtime engine switching
  - Pattern Analyzer: identifies endpoint patterns and technology stack
  - WAF Bypass Engine: detects and bypasses web application firewalls
  - Approval Workflow: interactive approval with risk-based confirmation
  - Rate Limiter: adaptive throttling and concurrency control
  - Reporter: structured output (terminal, JSON, HTML)
  - Plugins: auth-attack, kubernetes, llm-attack (HashiCorp go-plugin)

# Security

This tool is designed for AUTHORIZED security testing only.  Always obtain
explicit written permission before testing any systems you do not own.

Unauthorized access to computer systems is illegal under laws including but
not limited to the Computer Fraud and Abuse Act (CFAA) in the United States
and the Computer Misuse Act in the United Kingdom.

The authors assume no liability for misuse or damage caused by this program.

# Documentation

Full documentation is available at:

  - GitHub: https://github.com/htunn/simple-exploit
  - pkg.go.dev: https://pkg.go.dev/github.com/htunn/simple-exploit
  - Releases: https://github.com/htunn/simple-exploit/releases

# Support

  - Issue Tracker: https://github.com/htunn/simple-exploit/issues
  - Discussions: https://github.com/htunn/simple-exploit/discussions
  - Documentation: https://github.com/htunn/simple-exploit/tree/main/docs

# License

MIT License — see LICENSE file for details.
*/
package simpleexploit