Quickstart

Install the CLI and store your token. The token is saved to ~/.rank-cli/credentials.

npm install -g @aleex-rank/cli
rank auth set rk_live_xxxxxxxxxxxxxxxx

Create an automatic web pentest with https://example.com as the primary asset.

rank pentest create \
  --name "Quickstart" \
  --url https://example.com \
  --type web \
  --mode automatic

The command prints the new pentest id. Use it in the next steps.

An active Rules of Engagement is required before the run starts — set it from the web app, the SDK or the REST API (the CLI does not yet create RoE). The RoE must cover example.com (for example allowed_domains: ["example.com"]), include authorization_ref and at least one escalation contact, and be activated.

Run the pentest. In automatic mode the agents are auto-assigned and all phases stream to your terminal in real time.

rank pentest run 42

List the vulnerabilities the agents found once the run completes.

rank pentest vulns 42

Install the SDK and expose your token. The client reads RANK_API_KEY automatically, or you can pass api_key= explicitly.

pip install rank-sdk
export RANK_API_KEY=rk_live_xxxxxxxxxxxxxxxx

Create an automatic web pentest with https://example.com as the primary asset.

import rank

client = rank.Rank()

pentest = client.pentests.create(
    name="Quickstart",
    type="web",
    mode="automatic",
    assets=[
        {"asset_type": "url", "asset_value": "https://example.com", "is_primary": True},
    ],
)
print(pentest.id)

Activate a Rules of Engagement that covers the target. activate=True is what makes the run legal to start.

client.pentests.roe.create(
    pentest.id,
    allowed_domains=["example.com"],
    authorization_ref="ENG-2026-0042",
    escalation_contacts=[{"type": "email", "value": "security@example.com"}],
    activate=True,
)

Auto-assign the default agents, then stream execution. In automatic mode the agents chain every phase to completion and process findings in-stream.

client.pentests.agents.default(pentest.id)

with client.ai.chat.stream(
    user_prompt="Start the pentest on the configured targets",
    pentest_id=pentest.id,
    mode="automatic",
) as stream:
    for event in stream:
        if event.type == "content":
            print(event.content, end="", flush=True)

Read back the findings once the run completes.

summary = client.pentests.vulnerabilities.summary(pentest.id)
print(summary.by_severity)

for vuln in client.pentests.vulnerabilities.list(pentest.id).items:
    print(vuln.severity, vuln.vulnerability)

Create an automatic web pentest. CRUD lives on the PHP API at https://api.aleex-rank.ai/api/v2. The response includes the new pentest id.

curl https://api.aleex-rank.ai/api/v2/pentests \
  -H "X-API-Key: rk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Quickstart",
    "type": "web",
    "mode": "automatic",
    "assets": [
      {"asset_type": "url", "asset_value": "https://example.com", "is_primary": true}
    ]
  }'

Activate a Rules of Engagement that covers the target.

curl https://api.aleex-rank.ai/api/v2/pentests/42/roe \
  -H "X-API-Key: rk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "allowed_domains": ["example.com"],
    "authorization_ref": "ENG-2026-0042",
    "escalation_contacts": [{"type": "email", "value": "security@example.com"}],
    "activate": true
  }'

Trigger default-agent auto-assignment. For an automatic pentest this single call assigns the default agents to every phase (auto_assigned: true).

GET /api/v2/pentests/42/default-agents
X-API-Key: rk_live_xxxxxxxxxxxxxxxx

Start execution. Runs are orchestrated by the Go backend at https://aleex.aleex-rank.ai, which streams progress back over Server-Sent Events. Send user_prompt (not user_message).

curl https://aleex.aleex-rank.ai/chat \
  -H "X-API-Key: rk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_type": "pentest",
    "pentest_id": 42,
    "mode": "automatic",
    "user_prompt": "Run the full pentest automatically"
  }'

Read back the findings once the stream ends with a complete event.

GET /api/v2/pentests/42/vulnerabilities/summary
X-API-Key: rk_live_xxxxxxxxxxxxxxxx