securewithtrace 0.42.0 → 0.43.0

package/README.md

@@ -263,6 +263,9 @@ tracecli pentest findings list --pentest PT-3 --output tsv | cut -f1,4
 # Open the pentest detail page in a browser
 tracecli pentest findings list --pentest PT-3 --web
 
+# One finding with its full write-up, as markdown for a coding agent
+tracecli pentest findings get --pentest PT-3 --finding PTF-7
+
 # Mark a finding in progress, then remediated when the fix is ready for retest
 tracecli pentest findings status-update --pentest PT-3 --finding 7 --status IN_PROGRESS
 tracecli pentest findings status-update --pentest PT-3 --finding 7 --status REMEDIATED
@@ -284,6 +287,14 @@ Flags for `pentest findings list`:
 | `--output <format>` | `-o` | Output format: `table` (default), `json`, `tsv` |
 | `--web` | `-w` | Open the pentest detail page in a browser |
 
+Flags for `pentest findings get`:
+
+| Flag | Shorthand | Description |
+|------|-----------|-------------|
+| `--pentest <id>` | | Pentest display ID (e.g. `PT-3`) or UUID (required) |
+| `--finding <id>` | | Finding number (e.g. `PTF-7`) or UUID (required) |
+| `--output <format>` | `-o` | Output format: `text` (markdown, default), `json` |
+
 Flags for `pentest findings status-update`:
 
 | Flag | Shorthand | Description |

package/dist/index.js

@@ -46485,117 +46485,6 @@ Examples:
   });
 }
 
-// src/pentest/questionnaire.ts
-function buildUpsertQuestionnaireBody(answers) {
-  if (answers === null) {
-    return { answers: null };
-  }
-  return { answers: normalizePentestCustomerIntakeAnswers(answers) };
-}
-function parseQuestionnaireAnswersFile(raw, sourceLabel = "file") {
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    return { error: `Invalid JSON in ${sourceLabel}.` };
-  }
-  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-    return {
-      error: `${sourceLabel} must be a JSON object of questionnaire answers (not an array or null).`
-    };
-  }
-  if ("answers" in parsed && Object.keys(parsed).length === 1) {
-    return {
-      error: `${sourceLabel} must contain the answers object directly, not an { answers } wrapper. The CLI wraps it for the API.`
-    };
-  }
-  const result = PentestCustomerIntakeAnswersSchema.safeParse(parsed);
-  if (!result.success) {
-    const issue2 = result.error.issues[0];
-    const path = issue2?.path.length ? issue2.path.join(".") : "answers";
-    const message = issue2?.message ?? "invalid";
-    return { error: `Invalid questionnaire answers in ${sourceLabel}: ${path} \u2014 ${message}` };
-  }
-  return { answers: normalizePentestCustomerIntakeAnswers(result.data) };
-}
-function applyTextIntakeAnswer(current, key, input) {
-  const trimmed = input.trim();
-  if (trimmed.length === 0) {
-    return current;
-  }
-  return { ...current, [key]: trimmed };
-}
-function applyMultiSelectIntakeAnswer(current, key, selected) {
-  if (selected.length === 0) {
-    return current;
-  }
-  return {
-    ...current,
-    [key]: Array.from(new Set(selected)).sort()
-  };
-}
-function formatIssueClasses(values) {
-  return values.map((v) => INTAKE_ISSUE_CLASS_LABELS[v]).join(", ");
-}
-function formatSurfaces(values) {
-  return values.map((v) => INTAKE_SURFACE_LABELS[v]).join(", ");
-}
-function formatAnswerValue(key, answers) {
-  switch (key) {
-    case "issueClasses": {
-      const values = answers.issueClasses;
-      if (values === void 0 || values.length === 0) {
-        return null;
-      }
-      return formatIssueClasses(values);
-    }
-    case "surfaces": {
-      const values = answers.surfaces;
-      if (values === void 0 || values.length === 0) {
-        return null;
-      }
-      return formatSurfaces(values);
-    }
-    default: {
-      const value = answers[key];
-      if (value === void 0 || value.trim().length === 0) {
-        return null;
-      }
-      return value;
-    }
-  }
-}
-function formatQuestionnaireShow(input) {
-  const submitted = input.submitted === true;
-  const editableLine = input.editable ? "yes (scoping window open)" : submitted ? "no (submitted)" : "no (editing closed after scoping)";
-  const lines = [`Editable: ${editableLine}`, `Submitted: ${submitted ? "yes" : "no"}`];
-  if (input.answers === null || Object.keys(input.answers).length === 0) {
-    lines.push("Answers: (none)");
-    return lines.join("\n");
-  }
-  lines.push("Answers:");
-  for (const key of PENTEST_CUSTOMER_INTAKE_ANSWER_KEYS) {
-    const value = formatAnswerValue(key, input.answers);
-    if (value === null) {
-      continue;
-    }
-    lines.push(`${PENTEST_CUSTOMER_INTAKE_LABELS[key]}: ${value}`);
-  }
-  return lines.join("\n");
-}
-function issueClassSelectOptions() {
-  return CustomerPriorityCategoryValues.map((value) => ({
-    value,
-    label: INTAKE_ISSUE_CLASS_LABELS[value]
-  }));
-}
-function surfaceSelectOptions() {
-  return IntakeSurfaceValues.map((value) => ({
-    value,
-    label: INTAKE_SURFACE_LABELS[value]
-  }));
-}
-
 // src/pentest/status-update.ts
 var PENTEST_IDENTIFIER_PATTERN = /^(?:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|pt-\d+|\d+)$/i;
 var FINDING_IDENTIFIER_PATTERN = /^(?:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|ptf-\d+|\d+)$/i;
@@ -46777,6 +46666,257 @@ Examples:
   });
 }
 
+// src/pentest/get-finding.ts
+var OUTPUT_FORMATS2 = ["text", "json"];
+function isOutputFormat2(value) {
+  return OUTPUT_FORMATS2.includes(value);
+}
+var PROSE_SECTIONS = [
+  { key: "description", heading: "Description" },
+  { key: "impact", heading: "Impact" },
+  { key: "attackScenario", heading: "Attack Scenario" },
+  { key: "proofOfConcept", heading: "Proof of Concept" },
+  { key: "rootCauseAnalysis", heading: "Root Cause Analysis" },
+  { key: "remediation", heading: "Remediation" },
+  { key: "severityConsiderations", heading: "Severity Considerations" },
+  { key: "verification", heading: "Verification" }
+];
+function sanitizeMarkdown(value) {
+  return value.split("\n").map(sanitizeDisplay).join("\n");
+}
+function formatFindingMarkdown(finding) {
+  const lines = [];
+  lines.push(`# PTF-${finding.displayId}: ${sanitizeDisplay(finding.title)}`);
+  lines.push("");
+  lines.push(`- Severity: ${sanitizeDisplay(finding.severity)}`);
+  lines.push(`- Status: ${sanitizeDisplay(finding.status)}`);
+  lines.push(`- Category: ${sanitizeDisplay(finding.category)}`);
+  if (finding.cweIds.length > 0) {
+    lines.push(`- CWE: ${finding.cweIds.map(sanitizeDisplay).join(", ")}`);
+  }
+  if (finding.owaspCategory) {
+    lines.push(`- OWASP: ${sanitizeDisplay(finding.owaspCategory)}`);
+  }
+  if (finding.cvssScore !== null || finding.cvssVector) {
+    const parts = [
+      finding.cvssScore !== null ? String(finding.cvssScore) : null,
+      finding.cvssVector === null ? null : sanitizeDisplay(finding.cvssVector)
+    ].filter((part) => part !== null);
+    lines.push(`- CVSS: ${parts.join(" ")}`);
+  }
+  if (finding.repositories.length > 0) {
+    lines.push("");
+    lines.push("## Affected Code");
+    lines.push("");
+    for (const repository of finding.repositories) {
+      const repositoryName = sanitizeDisplay(repository.repositoryName);
+      const filePath = repository.filePath === null ? null : sanitizeDisplay(repository.filePath);
+      const location = filePath === null ? repositoryName : `${repositoryName}: ${filePath}${repository.startLine === null ? "" : `:${repository.startLine}${repository.endLine !== null && repository.endLine !== repository.startLine ? `-${repository.endLine}` : ""}`}`;
+      const commitSha = repository.commitSha === null ? null : sanitizeDisplay(repository.commitSha).slice(0, 12);
+      lines.push(`- ${location}${commitSha ? ` (commit ${commitSha})` : ""}`);
+    }
+  }
+  for (const section of PROSE_SECTIONS) {
+    const body = finding[section.key];
+    if (!body) continue;
+    lines.push("");
+    lines.push(`## ${section.heading}`);
+    lines.push("");
+    lines.push(sanitizeMarkdown(body.trim()));
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function failGetFinding(status, body) {
+  const { message } = readErrorFields(body);
+  if (status === UNAUTHORIZED_STATUS2) {
+    exitAuthFailed();
+  }
+  if (status === 404) {
+    console.error(colorError(message ?? "Pentest or finding not found."));
+    process.exit(1);
+  }
+  if (status === 403) {
+    console.error(colorError(message ?? "You do not have access to this finding (status 403)."));
+    process.exit(1);
+  }
+  console.error(
+    colorError(`Failed to fetch finding (status ${status})${message ? `: ${message}` : "."}`)
+  );
+  process.exit(1);
+}
+async function runGetFinding(options) {
+  if (!isOutputFormat2(options.output)) {
+    console.error(
+      colorError(`Invalid --output '${sanitizeDisplay(options.output)}'. Use text or json.`)
+    );
+    process.exit(1);
+  }
+  if (!isPentestIdentifier(options.pentest)) {
+    console.error(
+      colorError(
+        `Invalid pentest identifier '${sanitizeDisplay(options.pentest)}'. Use a display ID (e.g. PT-3) or UUID.`
+      )
+    );
+    process.exit(1);
+  }
+  if (!isFindingIdentifier(options.finding)) {
+    console.error(
+      colorError(
+        `Invalid finding identifier '${sanitizeDisplay(options.finding)}'. Use a finding number (e.g. PTF-7) or UUID.`
+      )
+    );
+    process.exit(1);
+  }
+  const organizationId = await resolveOrganizationId();
+  const result = await authenticatedRequest(
+    (client) => client.pentestFinding.getCustomerFinding({
+      params: {
+        organizationId,
+        pentestId: options.pentest,
+        pentestFindingId: options.finding
+      }
+    })
+  );
+  if (result.status !== 200) {
+    failGetFinding(result.status, result.body);
+  }
+  if (options.output === "json") {
+    console.log(JSON.stringify(result.body, null, 2));
+    return;
+  }
+  process.stdout.write(formatFindingMarkdown(result.body));
+}
+function createGetFindingCommand() {
+  return new Command("get").description("Fetch one pentest finding with its full write-up").requiredOption("--pentest <id>", "Pentest display ID (e.g. PT-3) or UUID").requiredOption("--finding <id>", "Finding number (e.g. PTF-7) or UUID").option("-o, --output <format>", "Output format: text (markdown), json (default: text)", "text").addHelpText(
+    "after",
+    `
+One finding, every section: description, impact, attack scenario, proof of
+concept, root cause, remediation, severity considerations, and verification,
+plus the affected repositories and lines. The default output is markdown, ready
+to paste into a coding agent; --output json returns the API response.
+
+Examples:
+  tracecli pentest findings get --pentest PT-3 --finding PTF-7
+  tracecli pentest findings get --pentest PT-3 --finding 7 --output json
+  tracecli pentest findings get --pentest PT-3 --finding PTF-7 > finding.md
+`
+  ).action(async (options) => {
+    await runGetFinding(options);
+  });
+}
+
+// src/pentest/questionnaire.ts
+function buildUpsertQuestionnaireBody(answers) {
+  if (answers === null) {
+    return { answers: null };
+  }
+  return { answers: normalizePentestCustomerIntakeAnswers(answers) };
+}
+function parseQuestionnaireAnswersFile(raw, sourceLabel = "file") {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { error: `Invalid JSON in ${sourceLabel}.` };
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return {
+      error: `${sourceLabel} must be a JSON object of questionnaire answers (not an array or null).`
+    };
+  }
+  if ("answers" in parsed && Object.keys(parsed).length === 1) {
+    return {
+      error: `${sourceLabel} must contain the answers object directly, not an { answers } wrapper. The CLI wraps it for the API.`
+    };
+  }
+  const result = PentestCustomerIntakeAnswersSchema.safeParse(parsed);
+  if (!result.success) {
+    const issue2 = result.error.issues[0];
+    const path = issue2?.path.length ? issue2.path.join(".") : "answers";
+    const message = issue2?.message ?? "invalid";
+    return { error: `Invalid questionnaire answers in ${sourceLabel}: ${path} \u2014 ${message}` };
+  }
+  return { answers: normalizePentestCustomerIntakeAnswers(result.data) };
+}
+function applyTextIntakeAnswer(current, key, input) {
+  const trimmed = input.trim();
+  if (trimmed.length === 0) {
+    return current;
+  }
+  return { ...current, [key]: trimmed };
+}
+function applyMultiSelectIntakeAnswer(current, key, selected) {
+  if (selected.length === 0) {
+    return current;
+  }
+  return {
+    ...current,
+    [key]: Array.from(new Set(selected)).sort()
+  };
+}
+function formatIssueClasses(values) {
+  return values.map((v) => INTAKE_ISSUE_CLASS_LABELS[v]).join(", ");
+}
+function formatSurfaces(values) {
+  return values.map((v) => INTAKE_SURFACE_LABELS[v]).join(", ");
+}
+function formatAnswerValue(key, answers) {
+  switch (key) {
+    case "issueClasses": {
+      const values = answers.issueClasses;
+      if (values === void 0 || values.length === 0) {
+        return null;
+      }
+      return formatIssueClasses(values);
+    }
+    case "surfaces": {
+      const values = answers.surfaces;
+      if (values === void 0 || values.length === 0) {
+        return null;
+      }
+      return formatSurfaces(values);
+    }
+    default: {
+      const value = answers[key];
+      if (value === void 0 || value.trim().length === 0) {
+        return null;
+      }
+      return value;
+    }
+  }
+}
+function formatQuestionnaireShow(input) {
+  const submitted = input.submitted === true;
+  const editableLine = input.editable ? "yes (scoping window open)" : submitted ? "no (submitted)" : "no (editing closed after scoping)";
+  const lines = [`Editable: ${editableLine}`, `Submitted: ${submitted ? "yes" : "no"}`];
+  if (input.answers === null || Object.keys(input.answers).length === 0) {
+    lines.push("Answers: (none)");
+    return lines.join("\n");
+  }
+  lines.push("Answers:");
+  for (const key of PENTEST_CUSTOMER_INTAKE_ANSWER_KEYS) {
+    const value = formatAnswerValue(key, input.answers);
+    if (value === null) {
+      continue;
+    }
+    lines.push(`${PENTEST_CUSTOMER_INTAKE_LABELS[key]}: ${value}`);
+  }
+  return lines.join("\n");
+}
+function issueClassSelectOptions() {
+  return CustomerPriorityCategoryValues.map((value) => ({
+    value,
+    label: INTAKE_ISSUE_CLASS_LABELS[value]
+  }));
+}
+function surfaceSelectOptions() {
+  return IntakeSurfaceValues.map((value) => ({
+    value,
+    label: INTAKE_SURFACE_LABELS[value]
+  }));
+}
+
 // src/pentest/commands.ts
 var DEFAULT_LIMIT2 = 30;
 var MAX_LIMIT2 = 100;
@@ -47147,6 +47287,7 @@ function renderPentestFindingLines(finding) {
 function createFindingsCommand() {
   const findings = new Command("findings").description("Manage pentest findings");
   findings.addCommand(createFindingsListCommand());
+  findings.addCommand(createGetFindingCommand());
   findings.addCommand(createStatusUpdateCommand());
   findings.addCommand(createAttachEvidenceCommand());
   findings.addCommand(createCreateFindingCommand(), { hidden: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "securewithtrace",
-  "version": "0.42.0",
+  "version": "0.43.0",
   "description": "Official Trace CLI for vulnerability intelligence in your terminal",
   "type": "module",
   "bin": {