Getting Started

OpenSploit is an open source AI-powered penetration testing agent. It orchestrates security tools through intelligent automation, guiding you through reconnaissance, enumeration, exploitation, and reporting phases.

Warning

OpenSploit is for authorized security testing only. You must have explicit written permission before testing any system. Unauthorized access to computer systems is illegal.

Prerequisites

To use OpenSploit, you'll need:

  1. Docker - Required for running security tools in containers
  2. A modern terminal emulator like WezTerm, Alacritty, Ghostty, or Kitty
  3. API keys for the LLM provider you want to use (or use Ollama for local models)

Install

The easiest way to install OpenSploit is through the install script:

curl -fsSL https://opensploit.ai/install | bash

You can also install using package managers:

Using npm:

npm install -g opensploit

Using Bun:

bun install -g opensploit

Using Homebrew (macOS/Linux):

brew install opensploit
Tip

Run opensploit doctor after installation to verify all dependencies are correctly installed.

Configure

OpenSploit supports 75+ LLM providers. You can use cloud providers like Claude, GPT, or Gemini, or run locally with Ollama.

  1. Run the /connect command to configure your provider:
/connect

  1. Select your provider and enter your API key.

  2. For local models with Ollama:

ollama pull llama3.2

Then select Ollama as your provider in OpenSploit.

Learn more about providers →

Quick Start

Navigate to a directory where you want to work:

cd /path/to/workspace

Start OpenSploit:

opensploit

Describe your target and objective in natural language:

Perform a security assessment on 10.10.10.1

OpenSploit will:

  1. Clarify the scope and target with you
  2. Begin reconnaissance (port scanning, service detection)
  3. Move through enumeration, exploitation, and reporting phases
  4. Request approval before each significant action

Practical Workflows

Reconnaissance

Ask OpenSploit to scan a target:

Scan 192.168.1.0/24 for open ports and services

The agent will use nmap to discover hosts and services, presenting findings as it goes.

Web Application Testing

Reference a target URL for web testing:

Test https://target.local for common web vulnerabilities

OpenSploit will enumerate directories, fingerprint technologies, and test for issues like SQL injection, XSS, and authentication bypasses.

Credential Testing

Test discovered credentials:

Try these credentials against the SSH service on 10.10.10.5

The agent will use tools like Hydra for credential testing, always requesting confirmation first.

Reporting

Generate a report at any point:

Generate a report of findings so far

OpenSploit compiles all discoveries, successful exploits, and recommendations into a structured report.

File References

Reference files in your prompts using the @ symbol:

Analyze the scan results in @nmap_results.xml

OpenSploit will include the file contents in context and reason about them.

Shell Commands

Execute shell commands directly by prefixing with !:

!docker ps

The output is included in the conversation, allowing follow-up questions.

Key Concepts

Phases

OpenSploit follows a structured penetration testing methodology:

| Phase | Description | |-------|-------------| | Reconnaissance | Port scanning, service detection, OS fingerprinting | | Enumeration | Directory bruteforcing, vulnerability scanning, version detection | | Exploitation | SQL injection testing, credential attacks, exploit execution | | Post-Exploitation | Privilege escalation, persistence, lateral movement | | Reporting | Findings aggregation, report generation |

Learn more about phases →

Tools

OpenSploit orchestrates 25+ security tools including nmap, sqlmap, ffuf, hydra, nuclei, and metasploit. Tools run in Docker containers and are downloaded on-demand.

Learn more about tools →

Agents

OpenSploit uses a hierarchical agent system. The master agent orchestrates specialized sub-agents for specific tasks, preventing context overload during long engagements.

Learn more about agents →

Safety

OpenSploit is for authorized security testing only. The system includes safeguards:

  • Warns before scanning external/non-private IP addresses
  • Requires explicit confirmation for external targets
  • Blocks scanning of forbidden targets (government, military, critical infrastructure)
  • Logs all scan authorizations for audit purposes

Learn more about security →