Quickstart

Go from zero to a finished automatic pentest with findings in a few minutes, from the CLI, the Python SDK or the REST API.

What you’ll build

This quickstart launches an automatic web pentest against https://example.com, lets the AI agents run every phase end to end, and then reads back the vulnerabilities they found.

Before you start you need an API token. Generate one in the dashboard at aleex-rank.ai under Settings > API Tokens. Tokens look like rk_live_... (production) or rk_test_... (sandbox) and are sent in the X-API-Key header. For the full picture, see Authentication & API tokens.

Guided vs automatic

A pentest runs in one of two modes:

automatic — the platform assigns default agents to every phase and chains the phases end to end with no further input. This is what the quickstart uses.
guided — you pick the agents for each phase and advance one phase at a time, giving you full control.

Both modes work the same across the CLI, SDK and API. See Core concepts for the mental model behind pentests, phases and agents.

Run your first pentest

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.
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)

Run the pentest. Auto-assign the default agents, then stream execution; in automatic mode the agents chain every phase to completion.

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):
    print(vuln.severity, vuln.title)

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}
    ]
  }'

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.

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_message": "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

In automatic mode the backend processes vulnerabilities and marks the pentest completed for you. In guided mode you advance phase by phase and finish the pentest yourself once findings are processed.

Next steps

Authentication & API tokens

JWT vs API tokens, scoped permissions and per-product setup.

Core concepts

Pentests, agents, vulnerabilities, teams and tiers explained.

Pentests, assets & phases

How modes, asset types and the three phases fit together.

Vulnerabilities

The finding lifecycle, severity, SLAs and evidence.