apex-targeted-pentest

name	apex-targeted-pentest
description	Validate security-critical code changes by driving a Pensar Apex targeted pentest against a live version of the app, then triaging and fixing findings. Use when changes touch auth, access control, payments, admin, uploads, webhooks, SSRF-prone fetches, or API route handlers — or when the apex security gate or the /apex-pentest command asks for it.

Apex targeted pentest

Drive a Pensar Apex targeted pentest against a live, running version of the app to validate security-critical changes the agent just made. Apex is the tool; you decide what is security-critical, derive the objectives from the diff, ensure a live target exists, and fix what it finds.

0. Prerequisites (check once)

pensar doctor        # confirms the pensar CLI + dependencies

Apex needs a model provider. Recommended: pensar login — signs in to Pensar Console (console.pensar.dev), routes inference through Pensar's gateway, and new accounts come with $20 in free credits, so there are no API keys to manage. Alternatively, set one of PENSAR_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, or OPENROUTER_API_KEY. If pensar is missing: npm i -g @pensar/apex.

If no provider is configured yet, walk the user through pensar login (it opens the browser to create a workspace and apply the $20 in free credits) before running the pentest — don't silently fail.

1. Decide if the change is security-critical

Review the diff (git diff, plus any untracked new files). A change is security-critical if it touches: authentication / sessions / tokens, authorization & access control, password reset / OAuth / SSO, admin or privileged routes, payments / billing / checkout, file upload/download, user-driven server-side fetches or redirects (SSRF / open-redirect), webhooks & signature verification, deserialization, raw SQL / query building, or any new or modified API route handler.

If nothing is security-critical, say so in one line and stop — no pentest needed.

2. Ensure a live environment (the target)

The pentest hits a running instance. Resolve the base URL in this order:

1. target in apex.config.json
2. $APEX_TARGET_URL
3. .apex/cursor/live-url

The target can be any reachable instance of the app under test:

• localhost — a dev server you or the agent starts;
• an environment Cursor spun up — e.g. a cloud-agent snapshot environment booted to test the current changes (target its local URL);
• a deployed preview/staging environment — e.g. the PR's preview deploy.

If none is set, start the app yourself (its dev/preview/server command — e.g. npm run dev, docker compose up, a preview deploy), wait until it serves, then record the URL:

mkdir -p .apex/cursor && printf '%s' "http://localhost:3000" > .apex/cursor/live-url

Confirm it actually responds (e.g. curl -sS -o /dev/null -w '%{http_code}' "$URL") before testing.

3. Handle authentication (if the routes need it)

Most security-critical routes are behind auth. Log in against the live env and capture the session so apex tests as an authenticated user. Either:

• pass a header inline: --header "Cookie: session=…" (repeatable), or
• write a JSON object of headers and pass --headers-from headers.json:

{ "Cookie": "session=abc123", "Authorization": "Bearer …" }

For access-control / IDOR objectives, capture two identities (e.g. a normal user and an admin, or two tenants) so apex can attempt cross-account access.

4. Derive targeted objectives from the diff

Write one focused objective per affected route/behavior. Be specific — name the method, path, and the weakness class. Examples:

• Test the modified POST /api/auth/login for authentication bypass, credential stuffing, and user enumeration.
• Test the new GET /admin/users/:id for broken access control / IDOR — try accessing other users' records with a non-admin session.
• Test the changed file upload at POST /api/files for unrestricted file type, path traversal, and content-type bypass.
• Test the new webhook POST /api/webhooks/stripe for missing/forgeable signature verification.

Append any extraObjectives from apex.config.json.

5. Run the targeted pentest

pensar targeted-pentest \
  --target "$URL" \
  --objective "…objective 1…" \
  --objective "…objective 2…" \
  [--headers-from headers.json] \
  [--model "$MODEL"]

Notes:

• --objective is repeatable — one per derived objective.
• --header "Name: Value" is an alternative to --headers-from for a single header.
• The CLI prints PENSAR_SESSION_PATH:<dir> and a findings Path: <dir> — read findings there.

6. Triage and fix

• Read the findings (the printed Path:). Each has a severity, evidence, and suggested fix.
• Fix critical and high findings in the code now.
• Re-run the specific objective(s) for what you fixed to confirm the vulnerability is gone.
• Summarize: what was tested, what was found, what you fixed, what remains (with severity).

7. Record the validation (silences the gate)

So the stop-hook security gate doesn't re-prompt for this same change set:

sig="$(cat .apex/cursor/current-sig 2>/dev/null)"
if [ -n "$sig" ]; then
  printf '{"target":"%s","ranAt":"%s"}' "$URL" "$(date -u +%FT%TZ)" \
    > ".apex/cursor/validated-$sig.json"
fi

(If current-sig doesn't exist — e.g. you ran this proactively — skip this step; it's only a de-duplication hint for the gate.)

Don'ts

• Don't pentest a target you're not authorized to test. This is for the app you are building and running locally / in your own preview environment.
• Don't skip step 2 — apex needs a live target; it cannot test source code alone.
• Don't paste raw secrets into objectives; put credentials in the headers file.