Metadata-Version: 2.4
Name: twpt-cli
Version: 1.0.0
Summary: ThreatWinds Pentest CLI - Command-line tool for managing automated penetration testing
Author-email: ThreatWinds <support@threatwinds.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/threatwinds/twpt-cli
Project-URL: Documentation, https://github.com/threatwinds/twpt-cli#readme
Project-URL: Repository, https://github.com/threatwinds/twpt-cli
Project-URL: Issues, https://github.com/threatwinds/twpt-cli/issues
Keywords: penetration-testing,security,pentesting,cli,threatwinds,kali-linux,docker
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Environment :: Console
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: urllib3>=2.0.0
Requires-Dist: grpcio>=1.60.0
Requires-Dist: grpcio-tools>=1.60.0
Requires-Dist: protobuf>=4.25.0
Requires-Dist: docker>=7.0.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: distro>=1.8.0
Requires-Dist: python-dateutil>=2.8.0
Requires-Dist: psutil>=5.9.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# ThreatWinds Pentest CLI

A powerful command-line interface for managing automated penetration testing using ThreatWinds' containerized Kali Linux environment. Schedule pentests, monitor progress in real-time, and download comprehensive security reports - all from your terminal.

## What Does This Tool Do?

The ThreatWinds Pentest CLI automates the process of running professional security assessments against your infrastructure:

1. **Automated Vulnerability Scanning**: Runs comprehensive security scans against target domains, IPs, or networks
2. **Penetration Testing**: Executes real-world attack simulations to identify exploitable vulnerabilities
3. **Real-time Monitoring**: Stream pentest progress and results as they happen via gRPC
4. **Evidence Collection**: Automatically generates and downloads detailed reports, screenshots, and proof-of-concept data
5. **Container Management**: Manages Docker containers running Kali Linux with pre-configured pentest tools
6. **Remote Execution**: Connect to remote pentest servers or run locally with Docker

**Use Cases**:
- Security teams running regular vulnerability assessments
- DevOps teams integrating security testing into CI/CD pipelines
- Penetration testers managing multiple client engagements
- Bug bounty hunters automating reconnaissance and testing

## Quick Start

**Want to get started right away? Here's the fastest path:**

```bash
# 1. Clone and setup
git clone https://github.com/threatwinds/pt-cli
cd pt-cli
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# 2. Initialize endpoint
python run.py init --local

# 3. Configure credentials
python run.py configure
# (Enter your ThreatWinds API key and secret)

# 4. Run a pentest
python run.py run example.com --watch

# 5. Download results
python run.py download <pentest-id>
```

That's it! Read on for detailed documentation.

---

## Features

- **Interactive Shell Mode**: Built-in interactive shell with command history and auto-completion
- **Easy Configuration**: Simple setup with API credentials and automatic Docker configuration
- **Remote Endpoint Support**: Connect to remote pentest services without local Docker
- **Automated Pentesting**: Schedule and manage penetration tests from the command line
- **Real-time Monitoring**: Watch pentest progress with streaming updates (gRPC)
- **Evidence Download**: Retrieve pentest reports and evidence with automatic extraction
- **Container Management**: Full control over the pentest Docker container
- **Cross-platform**: Supports all major Linux distributions

## Prerequisites

- **Python**: 3.8 or higher
- **Operating System**: Linux (for Docker functionality) or any OS (for remote endpoints)
- **ThreatWinds Account**: API credentials (get them at https://threatwinds.com/account)
- **Docker** (optional): Only needed if running pentests locally

## Project Structure

This project contains:

- **run.py** - Entry point to run the CLI
- **requirements.txt** - Python dependencies
- **twpt_cli/** - Main source code directory
  - **commands/** - All CLI commands (configure, run, get, download, etc.)
  - **sdk/** - SDK for API and gRPC communication
  - **config/** - Configuration and credential management
  - **docker/** - Docker container management
  - **main.py** - CLI application setup
  - **shell.py** - Interactive shell implementation
- **venv/** - Virtual environment (you create this)

**That's all you need!** Just run `python run.py` after installing dependencies.

## Installation & Setup

### Run from Source

This is currently the only installation method:

```bash
# 1. Clone the repository
git clone https://github.com/threatwinds/pt-cli
cd pt-cli

# 2. Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate  # On Linux/Mac
# OR
.\venv\Scripts\activate  # On Windows

# 3. Install dependencies
pip install -r requirements.txt

# 4. Run the CLI
python run.py --help
```

**Usage**: All commands use `python run.py` as shown throughout this documentation.

Examples:
```bash
python run.py configure
python run.py run example.com
python run.py get <pentest-id>
python run.py download <pentest-id>
```

## Remote Endpoints

The CLI supports connecting to remote ThreatWinds pentest services, allowing you to use the CLI without running Docker locally. This is useful for:

- Connecting to centralized pentest infrastructure
- Using the CLI on systems where Docker cannot be installed
- Accessing shared pentest services across teams

### Setting Up Remote Endpoints

**Step 1: Initialize the remote endpoint**

```bash
python run.py init --host <IP_ADDRESS> --api-port 9741 --grpc-port 9742
```

Example:
```bash
python run.py init --host 15.235.4.158 --api-port 9741
```

**Step 2: Configure API credentials (skip Docker setup)**

```bash
python run.py configure --skip-docker
```

**Step 3: Use the CLI normally**

```bash
python run.py run example.com
python run.py get <pentest-id>
python run.py download <pentest-id>
```

### Switching Between Local and Remote

**Switch to remote:**
```bash
python run.py init --host <remote-ip> --api-port 9741
```

**Switch back to local:**
```bash
python run.py init --local
```

### Checking Current Configuration

```bash
python run.py version --detailed
```

This will show whether you're using local Docker or a remote endpoint.

## Commands

### Interactive Shell

Start the interactive shell by running without arguments:

```bash
$ python run.py
```

**Shell Commands:**
- `run <target>` - Run a new pentest
- `get <id>` - Get pentest details
- `download <id>` - Download evidence
- `list` - List recent pentests
- `init <host> <port>` - Configure remote endpoint
- `configure` - Configure API credentials
- `status` - Show configuration status
- `update` - Update toolkit
- `uninstall` - Uninstall toolkit
- `version` - Show version
- `help [command]` - Show help
- `clear` - Clear screen
- `exit` / `quit` / `q` - Exit shell

**Features:**
- Command history (↑/↓ arrows)
- Tab auto-completion
- Persistent history across sessions
- Status indicators in prompt

### `init`

Initialize remote endpoint configuration.

**Options:**
- `--host`: Remote host IP address or hostname
- `--api-port`: API service port (default: 9741)
- `--grpc-port`: gRPC service port (default: 9742)
- `--skip-test`: Skip connection testing
- `--local`: Reset to local configuration (localhost)

**Examples:**
```bash
# Configure remote endpoint
python run.py init --host 15.235.4.158 --api-port 9741 --grpc-port 9742

# Reset to local configuration
python run.py init --local
```

### `configure`

Configure the CLI with API credentials and Docker setup.

**Options:**
- `--api-key`: ThreatWinds API Key
- `--api-secret`: ThreatWinds API Secret
- `--skip-docker`: Skip Docker setup (use with remote endpoints)

**Examples:**
```bash
# Interactive configuration
python run.py configure

# Non-interactive
python run.py configure --api-key YOUR_KEY --api-secret YOUR_SECRET

# Skip Docker (for remote endpoints)
python run.py configure --skip-docker
```

### `run` / `schedule-pentest`

Schedule a new penetration test.

**Command aliases:**
- `run` (simplified name)
- `schedule-pentest` (traditional name)

**Options:**
- `--config-file`: Path to JSON configuration file
- `--target`: Single target to pentest (or positional with `run`)
- `--targets`: Multiple targets (can be used multiple times)
- `--no-exploit`: Disable exploitation phase
- `--safe`: Use safe mode (less aggressive)
- `--watch`: Watch pentest progress in real-time

**Examples:**
```bash
# Simple scan (from source)
python run.py run example.com

# Safe mode with monitoring
python run.py run example.com --safe --watch

# Multiple targets
python run.py run --targets example.com --targets test.com

# Using config file
python run.py run --config-file pentest-config.json
```

**Example configuration file:**
```json
{
  "Style": "AGGRESSIVE",
  "Exploit": true,
  "Targets": [
    {
      "Target": "example.com",
      "Scope": "TARGETED",
      "Type": "BLACK_BOX"
    },
    {
      "Target": "test.example.com",
      "Scope": "HOLISTIC",
      "Type": "WHITE_BOX",
      "Credentials": {
        "username": "admin",
        "password": "secret"
      }
    }
  ]
}
```

### `get` / `get-pentest`

Get details of a specific pentest.

**Command aliases:**
- `get` (simplified name)
- `get-pentest` (traditional name)

**Arguments:**
- `pentest_id`: The unique identifier of the pentest

**Examples:**
```bash
# Check pentest status
python run.py get abc123def456
```

### `list` / `list-pentests`

List recent penetration tests.

**Examples:**
```bash
# List all pentests
python run.py list
```

### `download` / `download-evidence`

Download evidence/reports for a completed pentest.

**Command aliases:**
- `download` (simplified name)
- `download-evidence` (traditional name)

**Arguments:**
- `pentest_id`: The unique identifier of the pentest

**Options:**
- `--output`, `-o`: Output directory (default: current directory)
- `--no-extract`: Keep ZIP file without extracting

**Examples:**
```bash
# Download and extract evidence
python run.py download abc123def456

# Download to specific directory
python run.py download abc123def456 --output ./reports

# Keep ZIP without extracting
python run.py download abc123def456 --no-extract
```

### `update-latest`

Update the pentest toolkit to the latest version.

**Options:**
- `--force`: Force update even if container is running

**Examples:**
```bash
# Update toolkit
python run.py update-latest

# Force update
python run.py update-latest --force
```

### `uninstall`

Uninstall the pentest toolkit (removes Docker container and images).

**Options:**
- `--remove-data`: Also remove configuration and data files
- `--yes`: Skip confirmation prompt

**Examples:**
```bash
# Uninstall with confirmation
python run.py uninstall

# Uninstall and remove all data
python run.py uninstall --remove-data --yes
```

### `version`

Display version information.

**Options:**
- `--detailed`: Show detailed version information including configuration

**Examples:**
```bash
# Show version
python run.py version

# Show detailed version and config
python run.py version --detailed
```

## Complete Workflow Example

Here's a complete example of running a pentest from start to finish:

```bash
# 1. Activate virtual environment
source venv/bin/activate

# 2. Initialize endpoint (one-time setup)
python run.py init --local  # For local Docker
# OR
python run.py init --host 15.235.4.158 --api-port 9741  # For remote endpoint

# 3. Configure API credentials (one-time setup)
python run.py configure
# Enter your API key and secret when prompted

# 4. Schedule a pentest
python run.py run example.com --safe --watch
# This will output a pentest ID like: abc123def456

# 5. Check status (if not watching)
python run.py get abc123def456

# 6. List all pentests
python run.py list

# 7. Download results when complete
python run.py download abc123def456 --output ./reports

# 8. View the report
cd reports/abc123def456
ls -la  # See all evidence files and reports
```

## Configuration

The CLI stores configuration in two files:
- `~/.twpt/config.json`: API credentials (base64 encoded)
- `~/.twpt/endpoint.json`: Remote endpoint configuration (when using remote mode)

Environment variables:
- `PT_API_HOST`: Override API host (default: localhost)
- `PT_GRPC_HOST`: Override gRPC host (default: localhost)
- `PT_API_PORT`: Override API port (default: 9741)
- `PT_GRPC_PORT`: Override gRPC port (default: 9742)

**Note**: Remote endpoint configuration (set via `python run.py init`) takes precedence over environment variables.

## Docker Management

The CLI automatically manages a Docker container running the pentest agent:
- **Image**: `ghcr.io/threatwinds/twpt-agent:latest`
- **Container Name**: `twpt-agent`
- **Network**: Host network (required for pentesting)
- **Privileges**: Runs in privileged mode (required for pentesting)

### Manual Container Management

```bash
# Check container status
docker ps -a | grep twpt-agent

# View container logs
docker logs twpt-agent

# Restart container
docker restart twpt-agent

# Stop container
docker stop twpt-agent

# Remove container
docker rm twpt-agent
```

## Development

If you want to contribute or modify the code:

### Setup Development Environment

```bash
# Install dependencies
pip install -r requirements.txt

# Install optional development tools
pip install black isort mypy pytest
```

### Code Formatting

```bash
black twpt_cli/
isort twpt_cli/
```

### Type Checking

```bash
mypy twpt_cli/
```

### Run Tests

```bash
pytest tests/
```

## Architecture

The project structure:

```
twpt_cli/
├── main.py           # CLI application and command registration
├── shell.py          # Interactive shell implementation
├── sdk/              # SDK for API communication
│   ├── models.py         # Data models and enums
│   ├── http_client.py    # HTTP/REST client
│   ├── grpc_client.py    # gRPC streaming client
│   ├── pentest_pb2.py    # Protobuf definitions
│   └── pentest_pb2_grpc.py # gRPC stubs
├── config/           # Configuration management
│   ├── constants.py      # Constants and defaults
│   └── credentials.py    # Credential handling
├── docker/           # Docker container management
│   ├── container.py      # Container lifecycle
│   └── docker_install.py # Docker installation
└── commands/         # CLI command implementations
    ├── init.py               # Endpoint initialization
    ├── configure.py          # API credential setup
    ├── schedule_pentest.py   # Pentest scheduling
    ├── get_pentest.py        # Pentest status
    ├── download_evidence.py  # Evidence download
    ├── list_pentests.py      # List pentests
    ├── install_server.py     # Server installation
    ├── update.py             # Update toolkit
    ├── uninstall.py          # Uninstall toolkit
    └── version_cmd.py        # Version information
```

## Troubleshooting

### Docker Issues

If Docker installation fails:
```bash
# Manual Docker installation on Ubuntu/Debian
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add user to docker group
sudo usermod -aG docker $USER
```

### Container Connection Issues

If the CLI can't connect to the container:
```bash
# Check if container is running
docker ps | grep twpt-agent

# Restart container
docker restart twpt-agent

# Check container logs
docker logs twpt-agent --tail 50
```

### Permission Issues

If you get permission errors:
```bash
# Run with sudo (not recommended)
sudo python run.py configure

# Fix Docker permissions (recommended)
sudo usermod -aG docker $USER
newgrp docker
```

## Support

- **Documentation**: https://docs.threatwinds.com
- **Issues**: https://github.com/threatwinds/pt-cli/issues
- **Email**: support@threatwinds.com

## License

MIT License - see LICENSE file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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