Pentestas / help

Pentestas CLI

A lightweight Python CLI that wraps the Pentestas HTTP API. Built for CI — drop it into your pipeline and get a scan running on every merge to main.

Install

bash 
# From the Pentestas repo
git clone https://github.com/pentestas/pentestas.git
chmod +x pentestas/cli/pentestas
# Copy to your PATH:
cp pentestas/cli/pentestas /usr/local/bin/

Runtime requirements: Python 3.10+ and httpx (pip install httpx if not on the box).

Auth

bash 
# Option A: env var
export PENTESTAS_API_KEY=aa_…

# Option B: persist to ~/.pentestas/config.json (chmod 0600)
pentestas login
# Prompt: Paste your Pentestas API key:

API keys live in Settings → API keys in the web UI. Create one scoped to the user that should own the CI scans.

Commands

start

bash 
# Simple
pentestas start -u https://staging.example.com

# With a YAML config (auth flow, rules, etc.)
pentestas start -u https://app.example.com -c scan.yaml

# With a local repo for white-box mode
pentestas start -u https://app.example.com -r ./  -c scan.yaml

# Wait until complete (exits non-zero if any HIGH+ finding)
pentestas start -u https://app.example.com -w 1h

status

bash 
pentestas status <scan_id>
# Prints phase, finding count, and current progress message.

list

bash 
pentestas list --status running --limit 20
# One line per scan: <id>  <status>  <findings>  <target>

logs

bash 
pentestas logs <scan_id>

Replays the last ~2 hours of scan events. For live tailing, the CLI points at the web UI.

CI integration

GitHub Actions

yaml 
- name: Pentestas scan on staging
  env:
    PENTESTAS_API_KEY: ${{ secrets.PENTESTAS_API_KEY }}
  run: |
    curl -fsSL https://install.pentestas.com/cli | bash
    pentestas start \
      -u https://staging-${{ github.sha }}.example.com \
      -c .pentestas/scan.yaml \
      -r . \
      -w 45m

Exit codes: - 0 — scan completed, no HIGH/CRITICAL findings. - 1 — scan completed with HIGH/CRITICAL findings, or scan failed. - 2 — CLI usage error / timeout.

GitLab CI

yaml 
pentest:
  stage: security
  image: python:3.12-slim
  script:
    - pip install httpx
    - pentestas start -u $STAGING_URL -c .pentestas/scan.yaml -w 1h
  only:
    - main

Config file

~/.pentestas/config.json holds the API key:

json 
{
  "api_key": "aa_…",
  "base": "https://app.pentestas.com"
}

Override the base URL with PENTESTAS_BASE or pentestas login --base for self-hosted deployments.

See also