@prism-d1/cli 1.1.2 → 1.3.0

package/dist/src/security/pentest.js

@@ -0,0 +1,1057 @@
+/**
+ * `prism-cli security pentest`: run an AWS Security Agent penetration test
+ * against an application the caller owns, by deploying it into a fresh, private,
+ * temporary environment in the caller's account and testing only that.
+ *
+ * Design: docs/DESIGN-prism-cli-pentest.md (its open questions were resolved
+ * by a hand-run spike). It reuses the account/region/identity, the AWS-call
+ * seam (deps.aws), the CDK runner seam (deps.cdk), the pending-record and
+ * polling style, and the result cache from enable security / code-review.
+ *
+ * Version 1 only tests the environment it just deployed (no arbitrary URL):
+ * the target is built from the repo in front of it, deployed to a private VPC
+ * (no public endpoint, no internet gateway, no 0.0.0.0/0 ingress), reached by
+ * the pentest agent's ENI over local VPC routing, and verified by PRIVATE_VPC
+ * domain verification before the job starts.
+ *
+ * The AWS-writing and CDK/Docker-running parts go through seams, so tests run
+ * the whole orchestration against a fake account and a fake adapter.
+ */
+import { basename } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { isAbsolute, join, normalize } from 'node:path';
+import { makeResult, readResultEntries, writeResult, } from '../codewatch/results.js';
+import { redact } from './errors.js';
+import { Abort, call, preflight, printIdentity, resolveRegion, resolveRepo, NO_REGION_MESSAGE, } from './setup.js';
+import { POLL_FIRST_MS, POLL_MAX_MS, POLL_RETRIES, RETRY_FIRST_MS, RISK_ORDER, TERMINAL, resolveRepoRoot, } from './review.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** A pentest runs for hours (the spike took ~2h50m), so --wait defaults to 6h, not code-review's 30m. */
+export const PENTEST_DEFAULT_TIMEOUT_MIN = 360;
+/** Terminal job states (STOPPING is not terminal). Same set as code-review. */
+export { TERMINAL };
+export const FAIL_ON_LEVELS = ['critical', 'high', 'medium', 'low'];
+const RANK = { CRITICAL: 4, HIGH: 3, MEDIUM: 2, LOW: 1, INFORMATIONAL: 0, UNKNOWN: 0 };
+const riskRank = (r) => RANK[r] ?? 0;
+const DESCRIPTION_CHARS = 200;
+/** Findings per list-findings page and ids per batch-get-findings call (as code-review assumes). */
+const FINDINGS_PAGE = 100;
+const DETAILS_BATCH = 25;
+export const PENTEST_NOTICE = 'prism-cli security pentest deploys a TEMPORARY private environment (a VPC with private subnets only, Fargate behind an internal ALB, VPC endpoints, a service role, a source bucket and a log group) into the AWS account your credentials point to, builds and pushes your app image, uploads the repo at HEAD, registers and verifies a PRIVATE_VPC target domain, and starts an AWS Security Agent penetration test against that environment only. The environment is reachable only by the pentest agent; it has no public endpoint. It is torn down when the job finishes (--keep leaves it up, --cleanup removes it later).';
+export const COST_WARNING = 'Cost: AWS Security Agent penetration testing is billed in task-hours (publicly reported at $50 per task-hour, per-second metered; verify current pricing at the AWS Security Agent pricing page), plus the Fargate, internal ALB and VPC-endpoint running cost for as long as the environment is up. A run can last hours (the reference run took ~2h50m).';
+export const PENTEST_CONFIG_PATH = '.prism/pentest.json';
+/** Env var keys whose value must never be a literal in the committed file. */
+const SECRETY_KEY = /pass|secret|token|key|cred|pwd/i;
+const PROVIDER_TYPES = new Set(['SECRETS_MANAGER', 'AWS_LAMBDA', 'AWS_IAM_ROLE']);
+/**
+ * Loads and validates `.prism/pentest.json`. A sensitive-looking env value must
+ * be a Secrets Manager reference ({ "secret": "<arn>" }), never a literal, so
+ * no credential lands in the committed file.
+ */
+export function loadPentestConfig(repoRoot, override) {
+    const file = join(repoRoot, PENTEST_CONFIG_PATH);
+    let raw = {};
+    if (existsSync(file)) {
+        try {
+            raw = JSON.parse(readFileSync(file, 'utf8'));
+        }
+        catch (e) {
+            throw new Abort(`${PENTEST_CONFIG_PATH} is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    const appType = override?.appType || String(raw.appType || 'dockerfile');
+    // "path" is the Docker build context and "dockerfile" the Dockerfile, both
+    // relative to the repo root. --app-dir / --dockerfile override them; --path
+    // only picks the repo root. Neither may point outside the repo.
+    const inRepo = (v) => !isAbsolute(v) && !normalize(v).split(/[\\/]/).includes('..');
+    const path = String(override?.appDir || raw.path || '.');
+    if (!inRepo(path)) {
+        throw new Abort(`${override?.appDir ? '--app-dir' : `${PENTEST_CONFIG_PATH}: "path"`} must be a folder inside the repo (relative to the repo root, no ".."), got ${JSON.stringify(path)}`);
+    }
+    const dockerfile = String(override?.dockerfile || raw.dockerfile || join(path, 'Dockerfile'));
+    if (!inRepo(dockerfile)) {
+        throw new Abort(`${override?.dockerfile ? '--dockerfile' : `${PENTEST_CONFIG_PATH}: "dockerfile"`} must be a file inside the repo (relative to the repo root, no ".."), got ${JSON.stringify(dockerfile)}`);
+    }
+    const port = Number(raw.port ?? 8080);
+    if (!Number.isInteger(port) || port <= 0 || port > 65535)
+        throw new Abort(`${PENTEST_CONFIG_PATH}: "port" must be a TCP port, got ${JSON.stringify(raw.port)}`);
+    const healthPath = String(raw.healthPath || '/health');
+    if (!healthPath.startsWith('/'))
+        throw new Abort(`${PENTEST_CONFIG_PATH}: "healthPath" must start with "/", got ${JSON.stringify(raw.healthPath)}`);
+    const env = [];
+    const secretEnv = [];
+    const envObj = raw.env && typeof raw.env === 'object' ? raw.env : {};
+    for (const [name, v] of Object.entries(envObj)) {
+        if (v && typeof v === 'object' && typeof v.secret === 'string') {
+            if (!v.secret)
+                throw new Abort(`${PENTEST_CONFIG_PATH}: env "${name}" has an empty secret reference`);
+            secretEnv.push({ name, secret: v.secret });
+        }
+        else if (typeof v === 'string') {
+            if (SECRETY_KEY.test(name))
+                throw new Abort(`${PENTEST_CONFIG_PATH}: env "${name}" looks sensitive; give it as a Secrets Manager reference ({ "secret": "<arn>" }), never a literal value in the committed file.`);
+            env.push({ name, value: v });
+        }
+        else {
+            throw new Abort(`${PENTEST_CONFIG_PATH}: env "${name}" must be a string or { "secret": "<arn>" }`);
+        }
+    }
+    const actors = [];
+    for (const a of Array.isArray(raw.actors) ? raw.actors : []) {
+        const identifier = String(a?.identifier || '');
+        if (!identifier)
+            throw new Abort(`${PENTEST_CONFIG_PATH}: each actor needs an "identifier"`);
+        const auth = a?.auth || {};
+        const providerType = String(auth.providerType || 'SECRETS_MANAGER');
+        if (!PROVIDER_TYPES.has(providerType))
+            throw new Abort(`${PENTEST_CONFIG_PATH}: actor "${identifier}" providerType must be one of ${[...PROVIDER_TYPES].join(', ')}`);
+        const value = String(auth.secret || auth.value || '');
+        if (!value)
+            throw new Abort(`${PENTEST_CONFIG_PATH}: actor "${identifier}" needs a "secret"/"value" (an ARN; never a literal credential)`);
+        actors.push({ identifier, uris: Array.isArray(a.uris) ? a.uris.map(String) : undefined, auth: { providerType, value } });
+    }
+    const excludeRiskTypes = Array.isArray(raw.excludeRiskTypes) ? raw.excludeRiskTypes.map(String) : [];
+    return { appType, path, dockerfile, port, healthPath, env, secretEnv, actors, excludeRiskTypes };
+}
+export function toPentestJob(j) {
+    const steps = Array.isArray(j?.steps) ? j.steps : [];
+    const ctxs = Array.isArray(j?.executionContext) ? j.executionContext : [];
+    const running = steps.find((s) => s?.status === 'IN_PROGRESS');
+    const err = ctxs.filter((c) => c?.contextType === 'ERROR' || c?.contextType === 'CLIENT_ERROR').map((c) => String(c.context || '')).filter(Boolean);
+    const info = j?.errorInformation;
+    const reason = [err.join('; '), info ? `${info.code || ''}${info.message ? `: ${info.message}` : ''}` : ''].filter(Boolean).join('; ') || null;
+    return {
+        jobId: String(j?.pentestJobId || ''),
+        status: String(j?.status || 'UNKNOWN'),
+        step: running?.name ? String(running.name) : null,
+        reason,
+        overview: j?.overview ? firstParagraph(String(j.overview)) : null,
+        createdAt: j?.createdAt ? String(j.createdAt) : undefined,
+        updatedAt: j?.updatedAt ? String(j.updatedAt) : undefined,
+    };
+}
+function firstParagraph(s) {
+    const p = s.split(/\n\s*\n/)[0].replace(/\s+/g, ' ').trim();
+    return p.length > 500 ? `${p.slice(0, 499)}…` : p;
+}
+/** The id at the end of an ARN (`.../sg-123` -> `sg-123`); an id passes through. */
+const arnId = (arn) => arn.split('/').pop() || arn;
+/** The Env fields a stored record carries, for paths that rebuild a result from it. */
+function envOf(p) {
+    return { targetHost: p.target_host, stack: p.stack || '', slug: p.slug || '', expiresAt: p.expires_at || '', agentSgId: p.agent_security_group_id ?? null, appLogGroup: p.app_log_group ?? null, targetDomainId: p.target_domain_id ?? null };
+}
+/** Common pentest info fields for both the pending record and its completion. */
+function pentestInfo(o) {
+    return {
+        job_id: o.job.jobId, pentest_id: o.pentestId, agent_space_id: o.agentSpaceId, agent_space_dedicated: o.dedicated,
+        region: o.region, account: o.account, target_host: o.env.targetHost, job_status: o.job.status, counts: o.counts,
+        overview: o.job.overview ?? null, stack: o.env.stack || null, slug: o.env.slug || null, expires_at: o.env.expiresAt,
+        agent_security_group_id: o.env.agentSgId ?? null, app_log_group: o.env.appLogGroup ?? null,
+        target_domain_id: o.env.targetDomainId ?? null,
+        service_created_at: o.job.createdAt ?? null, service_updated_at: o.job.updatedAt ?? null,
+        service_duration_s: serviceSeconds(o.job), wall_s: o.wallS ?? null,
+    };
+}
+function serviceSeconds(job) {
+    if (!TERMINAL.has(job.status) || !job.createdAt || !job.updatedAt)
+        return null;
+    const a = Date.parse(job.createdAt), b = Date.parse(job.updatedAt);
+    return Number.isFinite(a) && Number.isFinite(b) && b >= a ? Math.round((b - a) / 1000) : null;
+}
+export function pendingPentestResult(o) {
+    return makeResult({
+        kind: 'security-pentest', hook: 'manual', tool: 'security-agent', status: 'pending',
+        commit: o.commit, branch: o.branch, started_at: o.startedAt, finished_at: o.startedAt,
+        pentest: pentestInfo({ ...o, counts: {} }),
+    });
+}
+function toSeverity(risk) {
+    return riskRank(risk) >= 3 ? 'high' : riskRank(risk) === 2 ? 'medium' : 'low';
+}
+function shortText(s) {
+    const one = redact(s).replace(/\s+/g, ' ').trim();
+    return one.length > DESCRIPTION_CHARS ? `${one.slice(0, DESCRIPTION_CHARS - 1)}…` : one;
+}
+export function countByRisk(fs) {
+    const c = Object.fromEntries(RISK_ORDER.map((r) => [r, 0]));
+    for (const f of fs)
+        c[RISK_ORDER.includes(f.riskLevel) ? f.riskLevel : 'UNKNOWN']++;
+    return c;
+}
+export function completedPentestResult(o) {
+    const counts = countByRisk(o.findings);
+    const ok = o.job.status === 'COMPLETED';
+    const findings = sortFindings(o.findings).map((f) => ({
+        severity: toSeverity(f.riskLevel), category: 'security', rule: f.riskType || f.title,
+        file: '', line: null, message: f.description ? `${f.title}: ${shortText(f.description)}` : f.title,
+        risk_level: f.riskLevel, title: f.title, cwe: null, finding_id: f.findingId, confidence: f.confidence,
+    }));
+    return makeResult({
+        kind: 'security-pentest', hook: 'manual', tool: 'security-agent',
+        status: !ok ? 'error' : findings.length ? 'findings' : 'ok',
+        commit: o.commit, branch: o.branch,
+        started_at: o.startedAt, finished_at: o.job.updatedAt || o.now.toISOString(),
+        findings,
+        summary: ok ? (o.job.overview || totalsLine(counts)) : null,
+        reason: ok ? null : `job ${o.job.status}${o.job.reason ? `: ${redact(o.job.reason)}` : ''}`,
+        pentest: pentestInfo({ ...o, counts }),
+    });
+}
+function sortFindings(fs) {
+    return [...fs].sort((a, b) => riskRank(b.riskLevel) - riskRank(a.riskLevel) || a.title.localeCompare(b.title));
+}
+export function totalsLine(c) {
+    const total = Object.values(c).reduce((a, b) => a + b, 0);
+    return `${total} finding${total === 1 ? '' : 's'}: ` + RISK_ORDER.map((r) => `${c[r]} ${r.toLowerCase()}`).join(', ');
+}
+// ---------------------------------------------------------------------------
+// Reads: job and findings
+// ---------------------------------------------------------------------------
+function jobArgs(agentSpaceId, jobId) {
+    return ['securityagent', 'batch-get-pentest-jobs', '--agent-space-id', agentSpaceId, '--pentest-job-ids', jobId];
+}
+export function getPentestJob(ctx, agentSpaceId, jobId) {
+    const j = (call(ctx, jobArgs(agentSpaceId, jobId)).json?.pentestJobs || [])[0];
+    if (!j)
+        throw new Abort(`No pentest job ${jobId} in agent space ${agentSpaceId}.`);
+    return toPentestJob(j);
+}
+function paged(ctx, args, key) {
+    const out = [];
+    let token;
+    for (let page = 0; page < 1000; page++) {
+        const r = call(ctx, [...args, '--max-items', String(FINDINGS_PAGE), ...(token ? ['--starting-token', token] : [])]);
+        out.push(...(r.json?.[key] || []));
+        token = r.json?.NextToken || r.json?.nextToken || undefined;
+        if (!token)
+            return out;
+    }
+    throw new Abort(`${args[1]} returned more than 1000 pages; stopping.`);
+}
+/** Pentest findings, dropping FALSE_POSITIVE confidence unless `includeFP`. */
+export function fetchPentestFindings(ctx, agentSpaceId, jobId, includeFP) {
+    const summaries = paged(ctx, ['securityagent', 'list-findings', '--agent-space-id', agentSpaceId, '--pentest-job-id', jobId], 'findingsSummaries');
+    const details = new Map();
+    for (let i = 0; i < summaries.length; i += DETAILS_BATCH) {
+        const ids = summaries.slice(i, i + DETAILS_BATCH).map((s) => String(s.findingId)).filter(Boolean);
+        if (!ids.length)
+            continue;
+        const r = ctx.deps.aws(['securityagent', 'batch-get-findings', '--agent-space-id', agentSpaceId, '--finding-ids', ...ids], ctx.opts.region);
+        if (r.ok)
+            for (const f of r.json?.findings || [])
+                details.set(String(f.findingId), f);
+    }
+    const all = summaries.map((s) => {
+        const d = details.get(String(s.findingId)) || {};
+        return {
+            findingId: String(s.findingId || ''),
+            riskLevel: String(d.riskLevel || s.riskLevel || 'UNKNOWN').toUpperCase(),
+            confidence: String(d.confidence || s.confidence || '').toUpperCase(),
+            title: String(d.name || s.name || '(untitled finding)'),
+            riskType: String(d.riskType || s.riskType || ''),
+            description: String(d.description || ''),
+        };
+    });
+    return includeFP ? all : all.filter((f) => f.confidence !== 'FALSE_POSITIVE');
+}
+export function failOnHit(fs, failOn) {
+    if (!failOn)
+        return false;
+    const min = riskRank(failOn.toUpperCase());
+    return fs.some((f) => riskRank(f.riskLevel) >= min && riskRank(f.riskLevel) > 0);
+}
+function printFindings(say, fs) {
+    const sorted = sortFindings(fs);
+    for (const level of RISK_ORDER) {
+        const group = sorted.filter((f) => f.riskLevel === level || (level === 'UNKNOWN' && !RISK_ORDER.includes(f.riskLevel)));
+        if (!group.length)
+            continue;
+        say(`${level} (${group.length})`);
+        for (const f of group) {
+            say(`  ${f.title}${f.confidence ? `  [${f.confidence.toLowerCase()} confidence]` : ''}`);
+            if (f.description)
+                say(`    ${shortText(f.description)}`);
+        }
+    }
+    say(totalsLine(countByRisk(fs)));
+}
+const mmss = (ms) => `${String(Math.floor(ms / 60000)).padStart(2, '0')}:${String(Math.floor(ms / 1000) % 60).padStart(2, '0')}`;
+const NOT_TRANSIENT = /ResourceNotFound|ValidationException|NotFound/;
+async function getJobRetrying(ctx, agentSpaceId, jobId, signal) {
+    const deps = ctx.deps;
+    const args = jobArgs(agentSpaceId, jobId);
+    for (let attempt = 0;; attempt++) {
+        const r = ctx.deps.aws(args, ctx.opts.region);
+        if (r.ok) {
+            const j = (r.json?.pentestJobs || [])[0];
+            if (!j)
+                throw new Abort(`No pentest job ${jobId} in agent space ${agentSpaceId}.`);
+            return toPentestJob(j);
+        }
+        if (NOT_TRANSIENT.test(r.raw) || attempt >= POLL_RETRIES)
+            throw new Abort(`${redact(r.raw).split('\n')[0]}\n${fetchLaterHint(ctx, jobId)}`);
+        const wait = RETRY_FIRST_MS * 2 ** attempt;
+        ctx.deps.log(`  Poll failed; retrying in ${wait / 1000}s (${attempt + 1}/${POLL_RETRIES})`);
+        await deps.sleep(wait, signal);
+        if (signal.aborted)
+            return null;
+    }
+}
+export async function pollPentest(ctx, agentSpaceId, first, timeoutMin) {
+    const deps = ctx.deps;
+    const start = deps.now().getTime();
+    const limit = timeoutMin * 60_000;
+    const ac = new AbortController();
+    let interrupted = false;
+    const off = deps.onInterrupt(() => { interrupted = true; ac.abort(); });
+    let job = first;
+    let delay = POLL_FIRST_MS;
+    try {
+        while (!TERMINAL.has(job.status)) {
+            const elapsed = deps.now().getTime() - start;
+            if (elapsed >= limit)
+                return { kind: 'timeout', job };
+            await deps.sleep(Math.min(delay, limit - elapsed), ac.signal);
+            if (interrupted)
+                return { kind: 'interrupted', job };
+            delay = Math.min(delay * 2, POLL_MAX_MS);
+            const next = await getJobRetrying(ctx, agentSpaceId, job.jobId, ac.signal);
+            if (!next)
+                return { kind: 'interrupted', job };
+            job = next;
+            const line = `[${mmss(deps.now().getTime() - start)}] ${job.status}${job.step ? ` (${job.step})` : ''}`;
+            if (deps.isTTY)
+                deps.ticker(line);
+            else
+                ctx.deps.log(`  ${line}`);
+        }
+        return { kind: 'done', job };
+    }
+    finally {
+        off();
+        if (deps.isTTY)
+            deps.ticker('');
+    }
+}
+/** The --profile/--region this run was given, so a printed follow-up command targets the same account and region. */
+export const followUpFlags = (ctx) => `${ctx.opts.profile ? ` --profile ${ctx.opts.profile}` : ''}${ctx.opts.regionSource === '--region' ? ` --region ${ctx.opts.region}` : ''}`;
+const cleanupCmd = (ctx) => `prism-cli security pentest --cleanup${followUpFlags(ctx)}`;
+const fetchLaterHint = (ctx, jobId) => `The job keeps running in AWS. Check it later with: prism-cli security pentest --status${followUpFlags(ctx)}  (or: prism-cli security findings --pentest ${jobId}${followUpFlags(ctx)})`;
+// ---------------------------------------------------------------------------
+// Helpers shared by the command paths
+// ---------------------------------------------------------------------------
+function begin(input, deps, readOnly, say) {
+    const r = resolveRegion(input, deps);
+    if (!r) {
+        say(`Error: ${NO_REGION_MESSAGE}`);
+        return null;
+    }
+    const opts = { ...input, region: r.region, regionSource: r.source };
+    return { opts, deps: { ...deps, log: say }, cliVersion: deps.awsVersion(), readOnly };
+}
+function checkedRoot(deps, path, say) {
+    try {
+        return resolveRepoRoot(deps, path);
+    }
+    catch (e) {
+        if (e instanceof Abort) {
+            say(`Error: ${redact(e.message)}`);
+            return null;
+        }
+        throw e;
+    }
+}
+function needRepo(ctx, root) {
+    const repo = resolveRepo(ctx.opts, ctx.deps, root);
+    if ('error' in repo)
+        throw new Abort(repo.error);
+    return repo;
+}
+async function confirm(ctx, question) {
+    const { deps, opts } = ctx;
+    if (opts.yes) {
+        deps.log(`--yes: approved.`);
+        return true;
+    }
+    if (!ctx.deps.isTTY) {
+        deps.log('Refusing to deploy or start anything: there is no terminal to confirm on. Re-run with --yes to approve, or --dry-run to only see the plan.');
+        return false;
+    }
+    const a = (await ctx.deps.ask(`${question} [y/N] `)).trim();
+    return /^y(es)?$/i.test(a);
+}
+function parseTimeout(v) {
+    if (v === undefined)
+        return PENTEST_DEFAULT_TIMEOUT_MIN;
+    const n = Number(v);
+    if (!Number.isFinite(n) || n <= 0)
+        throw new Abort(`--timeout must be a positive number of minutes, got "${v}"`);
+    return n;
+}
+function parseLevel(flag, v) {
+    if (v === undefined)
+        return undefined;
+    if (!FAIL_ON_LEVELS.includes(v.toLowerCase()))
+        throw new Abort(`${flag} must be one of: ${FAIL_ON_LEVELS.join(', ')}`);
+    return v.toLowerCase();
+}
+/** The newest security-pentest record for this account+region (pending first, else any), used by --status/--cleanup/findings. */
+export function latestPentestEntry(root, account, region, jobId) {
+    const entries = readResultEntries(root)
+        .filter(({ result: r }) => r.kind === 'security-pentest' && r.pentest?.account === account && r.pentest?.region === region && (!jobId || r.pentest?.job_id === jobId))
+        .sort((a, b) => b.result.started_at.localeCompare(a.result.started_at));
+    // A pending record is the one still driving an environment; then one whose
+    // environment is still up (a failed teardown, a health timeout); then the newest.
+    return entries.find((e) => e.result.status === 'pending')
+        ?? entries.find((e) => e.result.pentest?.stack)
+        ?? entries[0] ?? null;
+}
+const mmssOf = (ms) => `${String(Math.floor(ms / 60000)).padStart(2, '0')}:${String(Math.floor(ms / 1000) % 60).padStart(2, '0')}`;
+const profileHint = (ctx) => `--region ${ctx.opts.region}${ctx.opts.profile ? ` --profile ${ctx.opts.profile}` : ''}`;
+// ---------------------------------------------------------------------------
+// Healthy target wait
+// ---------------------------------------------------------------------------
+/** cdk deploy returns before the ALB has a healthy target; starting then gets 503s and PREFLIGHT fails. */
+export const HEALTH_TIMEOUT_MS = 10 * 60_000;
+export const HEALTH_POLL_MS = 15_000;
+function targetStates(ctx, tgArn) {
+    const r = call(ctx, ['elbv2', 'describe-target-health', '--target-group-arn', tgArn]);
+    return (r.json?.TargetHealthDescriptions || []).map((d) => ({
+        state: String(d?.TargetHealth?.State || 'unknown'),
+        reason: String(d?.TargetHealth?.Reason || ''),
+        description: String(d?.TargetHealth?.Description || ''),
+    }));
+}
+const describeTargets = (ts) => ts.length
+    ? ts.map((t) => `${t.state}${t.reason ? ` (${t.reason})` : ''}${t.description ? `: ${t.description}` : ''}`).join('; ')
+    : 'no targets registered yet';
+/**
+ * Polls the ALB target group until at least one target is `healthy`. On
+ * timeout aborts with the targets' state, reason and description and how to
+ * read the app's logs -- before anything is created in Security Agent.
+ */
+export async function waitForHealthyTarget(ctx, env, say, timeoutMs = HEALTH_TIMEOUT_MS) {
+    const deps = ctx.deps;
+    const start = deps.now().getTime();
+    say(`Waiting for the app to pass the ALB health check (up to ${Math.round(timeoutMs / 60_000)} min)...`);
+    const never = new AbortController().signal;
+    for (;;) {
+        const ts = targetStates(ctx, env.targetGroupArn);
+        const elapsed = deps.now().getTime() - start;
+        if (ts.some((t) => t.state === 'healthy')) {
+            say(`  [${mmssOf(elapsed)}] healthy`);
+            return;
+        }
+        say(`  [${mmssOf(elapsed)}] ${describeTargets(ts)}`);
+        if (elapsed >= timeoutMs) {
+            throw new Abort([
+                `the app never passed the ALB health check within ${Math.round(timeoutMs / 60_000)} min, so no pentest was created.`,
+                `Targets: ${describeTargets(ts)}`,
+                `App logs (log group ${env.appLogGroup}): aws logs tail ${env.appLogGroup} --since 30m ${profileHint(ctx)}`,
+                `The environment is left up so you can read them; remove it with: ${cleanupCmd(ctx)}`,
+            ].join('\n'));
+        }
+        await deps.sleep(Math.min(HEALTH_POLL_MS, timeoutMs - elapsed), never);
+    }
+}
+// ---------------------------------------------------------------------------
+// Teardown
+// ---------------------------------------------------------------------------
+/** Security Agent removes its ENIs a while after a job ends; the stack cannot delete the subnets/SG until then. */
+export const ENI_DRAIN_TIMEOUT_MS = 10 * 60_000;
+export const ENI_POLL_MS = 15_000;
+const TAIL_LINES = 20;
+/** Waits until no ENI uses the agent security group. Returns how many remained (0 = drained). */
+async function waitForEnisDrained(ctx, sgId, say) {
+    const deps = ctx.deps;
+    const start = deps.now().getTime();
+    const never = new AbortController().signal;
+    let announced = false;
+    for (;;) {
+        const r = ctx.deps.aws(['ec2', 'describe-network-interfaces', '--filters', `Name=group-id,Values=${sgId}`], ctx.opts.region);
+        if (!r.ok) {
+            say(`  could not list the agent's network interfaces (${redact(r.raw).split('\n')[0]}); deleting the stack anyway`);
+            return 0;
+        }
+        const enis = r.json?.NetworkInterfaces || [];
+        if (!enis.length) {
+            if (announced)
+                say('  the agent network interfaces are gone');
+            return 0;
+        }
+        const elapsed = deps.now().getTime() - start;
+        say(`  [${mmssOf(elapsed)}] waiting for ${enis.length} agent network interface(s) to be released (${enis.map((e) => `${e.NetworkInterfaceId} ${e.Status || ''}`.trim()).join(', ')})`);
+        announced = true;
+        if (elapsed >= ENI_DRAIN_TIMEOUT_MS)
+            return enis.length;
+        await deps.sleep(Math.min(ENI_POLL_MS, ENI_DRAIN_TIMEOUT_MS - elapsed), never);
+    }
+}
+/** The stack's DELETE_FAILED events, newest first, one line each. */
+function deleteFailures(ctx, stack) {
+    const r = ctx.deps.aws(['cloudformation', 'describe-stack-events', '--stack-name', stack], ctx.opts.region);
+    if (!r.ok)
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const e of r.json?.StackEvents || []) {
+        if (e?.ResourceStatus !== 'DELETE_FAILED' || seen.has(e.LogicalResourceId))
+            continue;
+        seen.add(e.LogicalResourceId);
+        out.push(`${e.LogicalResourceId} (${e.ResourceType}): ${redact(String(e.ResourceStatusReason || ''))}`);
+    }
+    return out.slice(0, 10);
+}
+/** How long one stack deletion may take (VPC endpoints, the ALB and the bucket-emptying custom resource). */
+export const STACK_DELETE_TIMEOUT_MS = 30 * 60_000;
+export const STACK_POLL_MS = 15_000;
+const GONE = /does not exist/;
+/**
+ * Deletes the recorded stack with CloudFormation directly and waits for it to
+ * go. No synth: `cdk destroy` re-synthesizes the app, which needs the deploy's
+ * full context (appDir, ...) and lookups, and failed before reaching
+ * CloudFormation. On failure prints the error tail and DELETE_FAILED resources.
+ */
+async function deleteStackOnce(ctx, stack, say) {
+    const deps = ctx.deps;
+    const never = new AbortController().signal;
+    const fail = (raw, what) => {
+        const lines = redact(raw).trimEnd().split('\n').filter(Boolean);
+        say(`  ${what} for ${stack} failed. Last lines:`);
+        for (const l of lines.slice(-TAIL_LINES))
+            say(`    ${l}`);
+        return { ok: false, reason: lines.pop() || what };
+    };
+    say(`  deleting the environment stack ${stack} (a few minutes)...`);
+    const del = ctx.deps.aws(['cloudformation', 'delete-stack', '--stack-name', stack], ctx.opts.region);
+    if (!del.ok)
+        return GONE.test(del.raw) ? { ok: true, reason: '' } : fail(del.raw, 'delete-stack');
+    const start = deps.now().getTime();
+    for (;;) {
+        const d = ctx.deps.aws(['cloudformation', 'describe-stacks', '--stack-name', stack], ctx.opts.region);
+        if (!d.ok) {
+            if (GONE.test(d.raw)) {
+                say(`  deleted the environment stack ${stack}`);
+                return { ok: true, reason: '' };
+            }
+            return fail(d.raw, 'describe-stacks');
+        }
+        const s = d.json?.Stacks?.[0] || {};
+        const status = String(s.StackStatus || 'UNKNOWN');
+        if (status === 'DELETE_COMPLETE') {
+            say(`  deleted the environment stack ${stack}`);
+            return { ok: true, reason: '' };
+        }
+        const elapsed = deps.now().getTime() - start;
+        if (status === 'DELETE_FAILED' || elapsed >= STACK_DELETE_TIMEOUT_MS) {
+            const reason = status === 'DELETE_FAILED' ? `DELETE_FAILED: ${redact(String(s.StackStatusReason || ''))}` : `still ${status} after ${Math.round(STACK_DELETE_TIMEOUT_MS / 60_000)} min`;
+            say(`  stack ${stack}: ${reason}`);
+            const failed = deleteFailures(ctx, stack);
+            if (failed.length) {
+                say('  Resources that failed to delete:');
+                for (const f of failed)
+                    say(`    ${f}`);
+            }
+            return { ok: false, reason };
+        }
+        say(`  [${mmssOf(elapsed)}] ${status}`);
+        await deps.sleep(Math.min(STACK_POLL_MS, STACK_DELETE_TIMEOUT_MS - elapsed), never);
+    }
+}
+/**
+ * Tears down the environment an entry recorded: stop a running job, delete the
+ * pentest and a dedicated agent space, wait for the agent's ENIs to drain, then
+ * delete the recorded stack, retrying once after another drain. Best effort per step,
+ * so it can be re-run. Writes the record: environment cleared on success, a
+ * `teardown_failed` marker (stack kept for --cleanup) on failure. Returns ok.
+ */
+async function teardown(ctx, root, entry, say) {
+    const p = entry.result.pentest;
+    const tryCall = (args, what) => {
+        const r = ctx.deps.aws(args, ctx.opts.region);
+        say(r.ok ? `  ${what}` : `  ${what}: skipped (${redact(r.raw).split('\n')[0]})`);
+    };
+    if (p.job_id && !TERMINAL.has(p.job_status))
+        tryCall(['securityagent', 'stop-pentest-job', '--agent-space-id', p.agent_space_id, '--pentest-job-id', p.job_id], 'stopped the job');
+    if (p.pentest_id)
+        tryCall(['securityagent', 'batch-delete-pentests', '--agent-space-id', p.agent_space_id, '--pentest-ids', p.pentest_id], 'deleted the pentest');
+    if (p.agent_space_dedicated && p.agent_space_id)
+        tryCall(['securityagent', 'delete-agent-space', '--agent-space-id', p.agent_space_id], 'deleted the dedicated agent space');
+    // After the agent space, which references it. Records from before the id was kept have none.
+    if (p.target_domain_id)
+        tryCall(['securityagent', 'delete-target-domain', '--target-domain-id', p.target_domain_id], 'deleted the target domain');
+    if (!p.stack) {
+        if (p.target_domain_id)
+            writeResult(root, { ...entry.result, pentest: { ...p, target_domain_id: null } }, entry.id);
+        return true;
+    }
+    const drain = () => (p.agent_security_group_id ? waitForEnisDrained(ctx, p.agent_security_group_id, say) : Promise.resolve(0));
+    await drain();
+    let r = await deleteStackOnce(ctx, p.stack, say);
+    if (!r.ok) {
+        say('  retrying once after the agent network interfaces drain...');
+        await drain();
+        r = await deleteStackOnce(ctx, p.stack, say);
+    }
+    const now = ctx.deps.now().toISOString();
+    if (r.ok) {
+        writeResult(root, { ...entry.result, pentest: { ...p, stack: null, slug: null, teardown_failed: null, target_domain_id: null } }, entry.id);
+        say('Environment torn down; the result record is kept.');
+        return true;
+    }
+    writeResult(root, { ...entry.result, pentest: { ...p, teardown_failed: { at: now, reason: r.reason } } }, entry.id);
+    say(`Teardown failed; the stack ${p.stack} is still up (and may cost money). Retry with: ${cleanupCmd(ctx)}`);
+    return false;
+}
+/**
+ * The environment stack a record belongs to: the stored name, else the slug,
+ * else derived from the target host. shortcut: the derivation follows the
+ * dockerfile adapter's naming (PrismPentest-<slug>, app.<slug>.prism.internal)
+ * and exists for records whose earlier teardown cleared the name; drop it once
+ * those records are gone.
+ */
+export function recordedStackName(p) {
+    if (p.stack)
+        return p.stack;
+    const slug = p.slug || /^app\.(.+)\.prism\.internal$/.exec(p.target_host || '')?.[1];
+    return slug ? `PrismPentest-${slug}` : null;
+}
+/** Does the stack exist (and is not DELETE_COMPLETE)? null when it cannot be told. */
+function stackExists(ctx, stack) {
+    const r = ctx.deps.aws(['cloudformation', 'describe-stacks', '--stack-name', stack], ctx.opts.region);
+    if (r.ok)
+        return String(r.json?.Stacks?.[0]?.StackStatus || '') !== 'DELETE_COMPLETE';
+    return GONE.test(r.raw) ? false : null;
+}
+export function teardownFailedLine(ctx, p) {
+    return `Teardown failed at ${p.teardown_failed.at}: ${p.teardown_failed.reason}. The stack ${p.stack} is still up; retry with: ${cleanupCmd(ctx)}`;
+}
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+/** `prism-cli security pentest`. Returns the exit code. */
+export async function securityPentest(input, deps, app) {
+    const say = deps.log;
+    const root = checkedRoot(deps, input.path, say);
+    if (!root)
+        return 1;
+    // --status and --cleanup act on an existing run and deploy nothing.
+    if (input.status || input.cleanup)
+        return runStatusOrCleanup(input, deps, app, root, say);
+    // Local checks first: a bad config, app type or Dockerfile path is reported
+    // before the notice and before any AWS call.
+    let cfg;
+    try {
+        cfg = loadPentestConfig(root, { appType: input.appType, appDir: input.appDir, dockerfile: input.dockerfile });
+        if (input.appType && input.appType !== app.type)
+            throw new Abort(`--app-type ${input.appType} is not supported; v1 ships "${app.type}".`);
+        if (cfg.appType !== app.type)
+            throw new Abort(`${PENTEST_CONFIG_PATH} appType "${cfg.appType}" is not supported; v1 ships "${app.type}".`);
+        if (!app.detect(join(root, cfg.path), join(root, cfg.dockerfile))) {
+            throw new Abort(`no ${app.type} app: build context ${cfg.path} / Dockerfile ${cfg.dockerfile} not found in the repo; set "path" and "dockerfile" in ${PENTEST_CONFIG_PATH}, or pass --app-dir / --dockerfile.`);
+        }
+    }
+    catch (e) {
+        if (e instanceof Abort) {
+            say(`Error: ${redact(e.message)}`);
+            return 1;
+        }
+        throw e;
+    }
+    say(PENTEST_NOTICE);
+    say('');
+    const ctx = begin(input, deps, false, say);
+    if (!ctx)
+        return 1;
+    try {
+        const failOn = parseLevel('--fail-on', input.failOn);
+        const timeout = parseTimeout(input.timeout);
+        const id = preflight(ctx);
+        printIdentity(ctx, id);
+        const repo = needRepo(ctx, root);
+        const plan = app.plan(ctx, repo, cfg);
+        say('');
+        say('Plan (no changes made yet):');
+        say(plan.diffText);
+        say('');
+        say(`Target:      ${plan.targetHost} (private; only this URL is in scope)`);
+        say(COST_WARNING);
+        if (input.dryRun) {
+            say('');
+            say('--dry-run: nothing was deployed or started.');
+            return 0;
+        }
+        say('');
+        if (!(await confirm(ctx, `Deploy this environment and start a penetration test in account ${id.account}, region ${ctx.opts.region}?`))) {
+            say('Aborted; nothing was changed.');
+            return 1;
+        }
+        // Deploy the private target environment.
+        say('Deploying the private target environment...');
+        const env = app.apply(ctx, repo, cfg, plan, true);
+        say(`Target up:   ${env.targetUrl}`);
+        const envRec = { targetHost: env.targetHost, stack: env.stack, slug: env.slug, expiresAt: env.expiresAt, agentSgId: arnId(env.agentSecurityGroupArn), appLogGroup: env.appLogGroup };
+        // Only start once the ALB serves the app: a 5xx target fails PREFLIGHT.
+        try {
+            await waitForHealthyTarget(ctx, env, say);
+        }
+        catch (e) {
+            if (!(e instanceof Abort))
+                throw e;
+            // Record the environment (no pentest exists) so --cleanup can remove it.
+            const at = deps.now().toISOString();
+            const path = writeResult(root, makeResult({
+                kind: 'security-pentest', hook: 'manual', tool: 'security-agent', status: 'error',
+                commit: gitLine(ctx, repo, ['rev-parse', 'HEAD']), branch: gitLine(ctx, repo, ['rev-parse', '--abbrev-ref', 'HEAD']),
+                started_at: at, finished_at: at, reason: 'the app never became healthy behind the ALB; no pentest was created',
+                pentest: pentestInfo({ job: { jobId: '', status: 'NOT_STARTED' }, pentestId: '', agentSpaceId: '', dedicated: false, region: ctx.opts.region, account: id.account, env: envRec, counts: {} }),
+            }));
+            say(`Error: ${redact(e.message)}`);
+            say(`Saved ${path}`);
+            return 1;
+        }
+        // Verify the target domain (PRIVATE_VPC: UNREACHABLE is OK, only FAILED is an error).
+        const domainId = createAndVerifyDomain(ctx, env.targetHost, say);
+        envRec.targetDomainId = domainId;
+        // Resolve the agent space, then the pentest, then start the job.
+        const { agentSpaceId, dedicated } = resolveAgentSpace(ctx, env, domainId, say);
+        const pentestId = createPentest(ctx, cfg, env, agentSpaceId, say);
+        const startJson = call(ctx, ['securityagent', 'start-pentest-job', '--agent-space-id', agentSpaceId, '--pentest-id', pentestId]).json;
+        const started = toPentestJob({ ...startJson, status: startJson?.status || 'IN_PROGRESS' });
+        if (!started.jobId)
+            throw new Abort('start-pentest-job returned no pentestJobId.');
+        say(`Started pentest job ${started.jobId}`);
+        const commit = gitLine(ctx, repo, ['rev-parse', 'HEAD']);
+        const branch = gitLine(ctx, repo, ['rev-parse', '--abbrev-ref', 'HEAD']);
+        const recordBase = { pentestId, agentSpaceId, dedicated, region: ctx.opts.region, account: id.account, env: envRec, commit, branch };
+        const startedAt = deps.now().toISOString();
+        let pendingId;
+        try {
+            const path = writeResult(root, pendingPentestResult({ ...recordBase, job: started, startedAt }));
+            pendingId = basename(path, '.json');
+            say(`Saved ${path} (pending)`);
+        }
+        catch (e) {
+            say(`Warning: could not save the pending record (${redact(e instanceof Error ? e.message : String(e))}).`);
+        }
+        if (!input.wait) {
+            say('');
+            say(`Not waiting (the default). The environment stays up until the job finishes.`);
+            say(`Check status:  prism-cli security pentest --status${followUpFlags(ctx)}`);
+            say(`               prism-cli security findings --pentest ${started.jobId}${followUpFlags(ctx)}`);
+            say(`Remove it now: ${cleanupCmd(ctx)}`);
+            return 0;
+        }
+        say(`Waiting for the job (up to ${timeout} min; Ctrl-C stops waiting, the job keeps running)...`);
+        const startMs = deps.now().getTime();
+        const out = await pollPentest(ctx, agentSpaceId, started, timeout);
+        if (out.kind === 'interrupted') {
+            say('');
+            say(`Stopped waiting. ${fetchLaterHint(ctx, started.jobId)}`);
+            return 130;
+        }
+        if (out.kind === 'timeout') {
+            say(`Timed out after ${timeout} min (job ${started.jobId} is ${out.job.status}). ${fetchLaterHint(ctx, started.jobId)}`);
+            return 2;
+        }
+        const wallS = Math.round((deps.now().getTime() - startMs) / 1000);
+        const findings = out.job.status === 'COMPLETED' ? fetchPentestFindings(ctx, agentSpaceId, started.jobId, !!input.includeFalsePositives) : [];
+        const result = completedPentestResult({ ...recordBase, job: out.job, startedAt, findings, now: deps.now(), wallS });
+        const path = writeResult(root, result, pendingId);
+        say('');
+        if (out.job.status === 'COMPLETED') {
+            if (out.job.overview) {
+                say(out.job.overview);
+                say('');
+            }
+            if (findings.length)
+                printFindings(say, findings);
+            else
+                say('No findings.');
+        }
+        else {
+            say(`Error: job ${started.jobId} ended ${out.job.status}${out.job.reason ? `: ${redact(out.job.reason)}` : ''}`);
+        }
+        say(`Saved ${path}`);
+        // Teardown unless --keep.
+        if (input.keep) {
+            say(`--keep: the environment stays up. Remove it later with: ${cleanupCmd(ctx)}`);
+        }
+        else {
+            say('Tearing down the environment...');
+            if (!(await teardown(ctx, root, { id: basename(path, '.json'), result }, say)))
+                return 1;
+        }
+        if (out.job.status !== 'COMPLETED')
+            return 1;
+        if (failOnHit(findings, failOn)) {
+            say(`--fail-on ${failOn}: findings at or above ${failOn}.`);
+            return 1;
+        }
+        return 0;
+    }
+    catch (e) {
+        if (e instanceof Abort) {
+            say(`Error: ${redact(e.message)}`);
+            return 1;
+        }
+        throw e;
+    }
+}
+/** --status (refresh + print, tear down on terminal unless --keep) and --cleanup (remove now). */
+async function runStatusOrCleanup(input, deps, app, root, say) {
+    if (input.cleanup)
+        say('Cleaning up the pentest environment (stops the job if running, deletes what the run created).');
+    else
+        say('Read-only status (refreshes the latest pentest job; tears the environment down only once the job has finished).');
+    say('');
+    const ctx = begin(input, deps, false, say);
+    if (!ctx)
+        return 1;
+    try {
+        const id = preflight(ctx);
+        printIdentity(ctx, id);
+        const entry = latestPentestEntry(root, id.account, ctx.opts.region);
+        if (!entry || !entry.result.pentest) {
+            say('No pentest runs recorded for this repo in this account and region.');
+            return 0;
+        }
+        const p = entry.result.pentest;
+        say(p.job_id ? `Pentest job: ${p.job_id} (recorded ${p.job_status}; target ${p.target_host})` : `No pentest job was started: ${redact(entry.result.reason || 'unknown')}`);
+        if (!p.stack && input.cleanup) {
+            // A finished record with no stack: either it really was deleted, or an
+            // older teardown cleared the name although the delete never happened.
+            // Look the stack up by its recorded (or derived) name and delete it if it is still there.
+            const name = recordedStackName(p);
+            if (!name) {
+                say('The record names no environment stack; nothing to delete.');
+                return 0;
+            }
+            const exists = stackExists(ctx, name);
+            if (exists === false) {
+                say(`The environment stack ${name} no longer exists.`);
+                if (p.target_domain_id)
+                    return (await teardown(ctx, root, entry, say)) ? 0 : 1;
+                return 0;
+            }
+            say(`The environment stack ${name} still exists${exists === null ? ' (or could not be checked)' : ''}; deleting it.`);
+            const revived = { id: entry.id, result: { ...entry.result, pentest: { ...p, stack: name, slug: name.replace(/^PrismPentest-/, '') } } };
+            say('Tearing down:');
+            return (await teardown(ctx, root, revived, say)) ? 0 : 1;
+        }
+        if (!p.stack) {
+            say('The environment for this run was already torn down.');
+            return 0;
+        }
+        if (p.teardown_failed)
+            say(teardownFailedLine(ctx, p));
+        if (input.cleanup) {
+            say('Tearing down:');
+            return (await teardown(ctx, root, entry, say)) ? 0 : 1;
+        }
+        // A failed teardown or a run that never started is retried by --cleanup only:
+        // --status stays a quick read, never a 10-minute ENI wait.
+        if (p.teardown_failed || !p.job_id) {
+            say(`Remove the environment with: ${cleanupCmd(ctx)}`);
+            return p.teardown_failed ? 1 : 0;
+        }
+        // --status: refresh the job.
+        const job = getPentestJob(ctx, p.agent_space_id, p.job_id);
+        say(`Now:         ${job.status}${job.step ? ` (${job.step})` : ''}`);
+        if (!TERMINAL.has(job.status)) {
+            say('Still running; check back later.');
+            return 0;
+        }
+        const findings = job.status === 'COMPLETED' ? fetchPentestFindings(ctx, p.agent_space_id, p.job_id, !!input.includeFalsePositives) : [];
+        const result = completedPentestResult({
+            job, pentestId: p.pentest_id, agentSpaceId: p.agent_space_id, dedicated: p.agent_space_dedicated,
+            region: ctx.opts.region, account: id.account, env: envOf(p),
+            commit: entry.result.commit, branch: entry.result.branch, startedAt: entry.result.started_at, findings, now: deps.now(),
+        });
+        const path = writeResult(root, result, entry.id);
+        say('');
+        if (job.status === 'COMPLETED') {
+            if (job.overview) {
+                say(job.overview);
+                say('');
+            }
+            if (findings.length)
+                printFindings(say, findings);
+            else
+                say('No findings.');
+        }
+        else
+            say(`Job ended ${job.status}${job.reason ? `: ${redact(job.reason)}` : ''}`);
+        say(`Saved ${path}`);
+        if (input.keep) {
+            say(`--keep: the environment stays up. Remove it with: ${cleanupCmd(ctx)}`);
+            return 0;
+        }
+        say('The job has finished; tearing the environment down:');
+        return (await teardown(ctx, root, { id: entry.id, result }, say)) ? 0 : 1;
+    }
+    catch (e) {
+        if (e instanceof Abort) {
+            say(`Error: ${redact(e.message)}`);
+            return 1;
+        }
+        throw e;
+    }
+}
+/**
+ * `prism-cli security findings --pentest [<job>]`. Read-only in AWS: refreshes
+ * the pentest job, completes the cached record in place, and prints the
+ * findings. Never tears the environment down (that is pentest --status /
+ * --cleanup). Returns the exit code.
+ */
+export async function securityPentestFindings(input, deps) {
+    const say = deps.log;
+    const root = checkedRoot(deps, input.path, say);
+    if (!root)
+        return 1;
+    say('Read-only (security findings --pentest): results are cached to .prism/results/; nothing in AWS is changed.');
+    say('');
+    const ctx = begin(input, deps, true, say);
+    if (!ctx)
+        return 1;
+    try {
+        const min = parseLevel('--severity', input.severity);
+        const timeout = parseTimeout(input.timeout);
+        const id = preflight(ctx);
+        printIdentity(ctx, id);
+        const entry = latestPentestEntry(root, id.account, ctx.opts.region, input.job);
+        if (!entry || !entry.result.pentest) {
+            say(input.job ? `No pentest record for job ${input.job} in this account and region.` : 'No pentest runs recorded for this repo in this account and region. Start one with: prism-cli security pentest');
+            return 0;
+        }
+        const p = entry.result.pentest;
+        if (!p.job_id) {
+            say(`The latest run never started a pentest job: ${redact(entry.result.reason || 'no job id recorded')}`);
+            return 1;
+        }
+        say(`Pentest job: ${p.job_id} (recorded ${p.job_status}; target ${p.target_host})`);
+        let job = getPentestJob(ctx, p.agent_space_id, p.job_id);
+        say(`Job:         ${job.status}${job.createdAt ? `, started ${job.createdAt}` : ''}`);
+        if (!TERMINAL.has(job.status)) {
+            if (!input.wait) {
+                say(`The job is still ${job.status}. Re-run with --wait to wait for it, or check back later.`);
+                return 2;
+            }
+            const out = await pollPentest(ctx, p.agent_space_id, job, timeout);
+            if (out.kind === 'interrupted') {
+                say('');
+                say(`Stopped waiting. ${fetchLaterHint(ctx, p.job_id)}`);
+                return 130;
+            }
+            if (out.kind === 'timeout') {
+                say(`Timed out after ${timeout} min (still ${out.job.status}). ${fetchLaterHint(ctx, p.job_id)}`);
+                return 2;
+            }
+            job = out.job;
+        }
+        const findings = job.status === 'COMPLETED' ? fetchPentestFindings(ctx, p.agent_space_id, p.job_id, !!input.includeFalsePositives) : [];
+        const result = completedPentestResult({
+            job, pentestId: p.pentest_id, agentSpaceId: p.agent_space_id, dedicated: p.agent_space_dedicated,
+            region: ctx.opts.region, account: id.account, env: envOf(p),
+            commit: entry.result.commit, branch: entry.result.branch, startedAt: entry.result.started_at, findings, now: deps.now(),
+        });
+        result.pentest.teardown_failed = p.teardown_failed ?? null;
+        const path = writeResult(root, result, entry.id);
+        say('');
+        if (p.teardown_failed)
+            say(teardownFailedLine(ctx, p));
+        if (job.status !== 'COMPLETED') {
+            say(`Error: job ${p.job_id} ended ${job.status}${job.reason ? `: ${redact(job.reason)}` : ''}`);
+            say(`Saved ${path}`);
+            return 1;
+        }
+        if (job.overview) {
+            say(job.overview);
+            say('');
+        }
+        const shown = min ? findings.filter((f) => riskRank(f.riskLevel) >= riskRank(min.toUpperCase()) && riskRank(f.riskLevel) > 0) : findings;
+        if (shown.length)
+            printFindings(say, shown);
+        else
+            say(min ? `No findings at ${min} or above.` : 'No findings.');
+        if (min && shown.length !== findings.length)
+            say(`(${findings.length - shown.length} below ${min} not shown; ${totalsLine(countByRisk(findings))})`);
+        say(`Saved ${path}`);
+        return 0;
+    }
+    catch (e) {
+        if (e instanceof Abort) {
+            say(`Error: ${redact(e.message)}`);
+            return 1;
+        }
+        throw e;
+    }
+}
+// ---------------------------------------------------------------------------
+// AWS steps (each a single call builder so dry-run/apply cannot disagree)
+// ---------------------------------------------------------------------------
+/** create-target-domain (PRIVATE_VPC) + verify. UNREACHABLE and VERIFIED/PENDING are OK; FAILED aborts. Returns the domain id. */
+export function createAndVerifyDomain(ctx, host, say) {
+    const created = call(ctx, ['securityagent', 'create-target-domain', '--target-domain-name', host, '--verification-method', 'PRIVATE_VPC',
+        '--tags', JSON.stringify({ 'prism:purpose': 'pentest' })]).json;
+    const domainId = String(created?.targetDomainId || '');
+    if (!domainId)
+        throw new Abort('create-target-domain returned no targetDomainId.');
+    const verified = call(ctx, ['securityagent', 'verify-target-domain', '--target-domain-id', domainId]).json;
+    const status = String(verified?.status || created?.verificationStatus || 'PENDING').toUpperCase();
+    if (status === 'FAILED')
+        throw new Abort(`target domain ${host} failed verification: ${redact(String(verified?.verificationStatusReason || ''))}`);
+    say(`Target domain ${host}: ${status}${status === 'UNREACHABLE' ? ' (expected for a private host; usable for PRIVATE_VPC pentests)' : ''}`);
+    return domainId;
+}
+/**
+ * The agent space to run in. v1 creates a DEDICATED pentest space per run (the
+ * spike-proven path), bound to the run's VPC, role, log group and target
+ * domain. shortcut: reuse the shared PrismD1SecurityAgent space via
+ * update-agent-space once that path is proven in an account (see the design's
+ * open question); reusing it untested risks the code-review space's config.
+ */
+export function resolveAgentSpace(ctx, env, domainId, say) {
+    const awsResources = JSON.stringify({
+        vpcs: [{ vpcArn: env.vpcArn, securityGroupArns: [env.agentSecurityGroupArn], subnetArns: env.subnetArns }],
+        iamRoles: [env.serviceRoleArn], logGroups: [env.logGroup],
+    });
+    const created = call(ctx, ['securityagent', 'create-agent-space', '--name', `pentest-${env.slug}`,
+        '--description', 'prism-cli security pentest (temporary, per-run)',
+        '--aws-resources', awsResources, '--target-domain-ids', domainId]).json;
+    const agentSpaceId = String(created?.agentSpaceId || '');
+    if (!agentSpaceId)
+        throw new Abort('create-agent-space returned no agentSpaceId.');
+    say(`Agent space: ${agentSpaceId} (dedicated to this run)`);
+    return { agentSpaceId, dedicated: true };
+}
+/** create-pentest with vpc-config (ONE subnet), a single ALLOW rule for the target URL, and the source zip. Returns the pentest id. */
+export function createPentest(ctx, cfg, env, agentSpaceId, say) {
+    const assets = { endpoints: [{ uri: env.targetUrl }] };
+    if (env.sourceZipS3)
+        assets.sourceCode = [{ s3Location: env.sourceZipS3 }];
+    if (cfg.actors.length)
+        assets.actors = cfg.actors.map((a) => ({ identifier: a.identifier, ...(a.uris ? { uris: a.uris } : {}), authentication: { providerType: a.auth.providerType, value: a.auth.value } }));
+    const args = ['securityagent', 'create-pentest', '--title', `prism-pentest-${env.slug}`, '--agent-space-id', agentSpaceId,
+        '--assets', JSON.stringify(assets),
+        '--service-role', env.serviceRoleArn,
+        '--log-config', JSON.stringify({ logGroup: env.logGroup }),
+        // create-pentest accepts exactly ONE subnet (spike-confirmed); the agent space holds the full list.
+        '--vpc-config', JSON.stringify({ vpcArn: env.vpcArn, securityGroupArns: [env.agentSecurityGroupArn], subnetArns: [env.pentestSubnetArn] }),
+        '--network-traffic-config', JSON.stringify({ rules: [{ effect: 'ALLOW', pattern: env.targetUrl, networkTrafficRuleType: 'URL' }] }),
+        '--code-remediation-strategy', 'DISABLED'];
+    if (cfg.excludeRiskTypes.length)
+        args.push('--exclude-risk-types', ...cfg.excludeRiskTypes);
+    const r = call(ctx, args).json;
+    const pentestId = String(r?.pentestId || '');
+    if (!pentestId)
+        throw new Abort('create-pentest returned no pentestId.');
+    say(`Pentest:     ${pentestId}`);
+    return pentestId;
+}
+function gitLine(ctx, repo, args) {
+    const r = ctx.deps.git(['-C', repo.root, ...args]);
+    return r.ok ? r.stdout.trim() : null;
+}
+//# sourceMappingURL=pentest.js.map