@secureport/sdk 0.5.0

package/src/resources/issues.ts

@@ -0,0 +1,344 @@
+// Issue, finding and comment types, and the /issues resource.
+import type { Requester } from '../client.js';
+import type { Page, PageQuery } from '../pagination.js';
+import { paginate } from '../pagination.js';
+
+/**
+ * Severity, most to least urgent: `critical`, `high`, `medium`, `low`,
+ * `advisory` — SDK-local, not imported from `@secureport/core`.
+ */
+export type Severity = 'critical' | 'high' | 'medium' | 'low' | 'advisory';
+
+/** Where an issue is in its lifecycle. There is no `triaging` state — see `@secureport/core`. */
+export type IssueStatus = 'open' | 'resolved' | 'regressed' | 'ignored';
+
+/**
+ * How an issue came into existence. Matters because **manual-origin issues
+ * never auto-resolve** — a human closes what a human opened.
+ */
+export type IssueOrigin = 'scan' | 'upload' | 'manual';
+
+/** Why an issue was suppressed — the fixed set the suppressed appendix groups by. */
+export type IgnoreReason = 'false_positive' | 'accepted_risk' | 'out_of_scope' | 'duplicate';
+
+/**
+ * How widely an ignore applies — `target` (this issue only, the default) or
+ * `org` (same weakness anywhere, matched on `vulnKey` and location).
+ */
+export type IgnoreScope = 'target' | 'org';
+
+/** What happened to an issue — the audit trail every issue carries. */
+export type IssueEventType =
+  | 'created'
+  | 'seen'
+  | 'severity_detected_changed'
+  | 'severity_overridden'
+  | 'resolved'
+  | 'reopened'
+  | 'ignored'
+  | 'unignored'
+  | 'commented'
+  | 'assigned'
+  | 'merged'
+  | 'retitled'
+  | 'exported';
+
+/**
+ * The tracked record that findings reconcile into. Mirrors
+ * `@secureport/core`'s `Issue`, with ISO 8601 strings in place of `Date` — parse what you need yourself.
+ */
+export interface Issue {
+  readonly id: string;
+  readonly orgId: string;
+  readonly targetId: string;
+  readonly fingerprint: string;
+  readonly fingerprintVersion: string;
+  readonly title: string;
+  readonly vulnKey: string;
+  readonly cwe?: string;
+  readonly location: string;
+  readonly parameter?: string;
+  readonly status: IssueStatus;
+  readonly detectedSeverity: Severity;
+  readonly effectiveSeverity: Severity;
+  readonly severityOverrideReason?: string;
+  readonly severityOverriddenBy?: string;
+  readonly severityOverriddenAt?: string;
+
+  /** Never reset — not by a regression, a severity change, or anything else. */
+  readonly firstSeen: string;
+  readonly lastSeen: string;
+  readonly resolvedAt?: string;
+  readonly reopenedAt?: string;
+  readonly consecutiveMisses: number;
+  readonly origin: IssueOrigin;
+  readonly assignee?: string;
+  readonly externalRef?: string;
+
+  /** Present only while `status` is `ignored`. */
+  readonly ignoreReason?: IgnoreReason;
+  readonly ignoreComment?: string;
+  readonly ignoreScope?: IgnoreScope;
+  readonly ignoreExpiresAt?: string;
+  readonly ignoredBy?: string;
+
+  /** Detected severity at the moment it was ignored — an increase re-surfaces the issue. */
+  readonly severityAtIgnore?: Severity;
+
+  /** `null` where the effective severity carries no SLA deadline. */
+  readonly slaDueAt: string | null;
+}
+
+/** One entry in an issue's append-only history. */
+export interface IssueEvent {
+  readonly id: string;
+  readonly orgId: string;
+  readonly issueId: string;
+
+  /** The run that caused it, where a run did. Absent for human actions. */
+  readonly runId?: string;
+  readonly type: IssueEventType;
+
+  /** A user id, an API key id, or the reconciler. Never absent. */
+  readonly actor: string;
+  readonly payload?: Readonly<Record<string, unknown>>;
+  readonly createdAt: string;
+}
+
+/**
+ * One detection, in one run — immutable evidence. Mirrors `@secureport/core`'s
+ * `Finding`; see {@link Issue} for why this is SDK-local rather than imported.
+ */
+export interface Finding {
+  readonly id: string;
+  readonly orgId: string;
+  readonly runId: string;
+  readonly fingerprint: string;
+  readonly fingerprintVersion: string;
+  readonly title: string;
+  readonly description?: string;
+  readonly detectedSeverity: Severity;
+  readonly severitySource: 'explicit' | 'cvss' | 'engine_default' | 'published_advisory';
+  readonly cvssScore?: number;
+  readonly cvssVector?: string;
+  readonly cwe?: string;
+  readonly cve?: string;
+  readonly vulnKey: string;
+  readonly category?: string;
+  readonly location: string;
+  readonly parameter?: string;
+  readonly port?: number;
+  readonly evidenceUri?: readonly string[];
+  readonly recommendation?: string;
+  readonly references?: readonly string[];
+  readonly sourceEngine: string;
+  readonly sourceRuleId?: string;
+  readonly confidence?: number;
+  readonly createdAt: string;
+}
+
+/**
+ * A comment on an issue — API-local, with no `@secureport/core` mirror.
+ * Permanent: never edited, never deleted.
+ */
+export interface IssueComment {
+  readonly id: string;
+  readonly orgId: string;
+  readonly issueId: string;
+  readonly author: string;
+  readonly body: string;
+  readonly createdAt: string;
+}
+
+/**
+ * One issue with everything hanging off it — what {@link IssuesResource.get}
+ * returns, not a bare {@link Issue}.
+ */
+export interface IssueDetail {
+  readonly issue: Issue;
+  readonly events: readonly IssueEvent[];
+  readonly findings: readonly Finding[];
+  readonly comments: readonly IssueComment[];
+}
+
+export type IssuePage = Page<Issue>;
+
+/**
+ * The filters `list`/`listAll` take, beside the page. All optional and
+ * combinable.
+ */
+export interface IssueFilters {
+  readonly status?: IssueStatus;
+
+  /** The effective severity — the one a human may have overridden. */
+  readonly severity?: Severity;
+  readonly targetId?: string;
+
+  /** ISO 8601. Issues seen on or after this instant (`lastSeen`). */
+  readonly since?: string;
+
+  /** e.g. `'CWE-79'`. */
+  readonly cwe?: string;
+
+  /** Full-text over title, vulnerability key and location. */
+  readonly search?: string;
+}
+
+export interface NewIssue {
+  readonly targetId: string;
+  readonly title: string;
+  readonly vulnKey: string;
+  readonly location: string;
+  readonly parameter?: string;
+  readonly cwe?: string;
+  readonly severity: Severity;
+}
+
+/**
+ * Retitles, assigns, or overrides severity — never status, which has its
+ * own endpoints (`resolve`/`ignore`/`unignore`), each with its own event.
+ */
+export interface IssuePatch {
+  /** A corrected title. */
+  readonly title?: string;
+
+  /** `null` unassigns. */
+  readonly assignee?: string | null;
+
+  /** A human's severity, with the reason it differs from the detected one. */
+  readonly severityOverride?: {
+    readonly severity: Severity;
+    readonly reason: string;
+  };
+}
+
+export interface NewIssueComment {
+  readonly body: string;
+}
+
+export interface ResolveInput {
+  /** Optional. What was changed, for whoever reads the history later. */
+  readonly comment?: string;
+}
+
+export interface IgnoreInput {
+  readonly reason: IgnoreReason;
+
+  /** Required. The register an auditor reads is only as good as this sentence. */
+  readonly comment: string;
+
+  /** `target` (default) or `org`. */
+  readonly scope?: IgnoreScope;
+
+  /**
+   * When the suppression lapses — omit for the server default (90 days for
+   * `accepted_risk`, none otherwise); pass `null` to force "never expires".
+   */
+  readonly expiresAt?: string | null;
+}
+
+/**
+ * Issues — the tracked entity findings reconcile into. Two scanners
+ * reporting one weakness produce one issue with two findings, not two.
+ */
+export class IssuesResource {
+  constructor(private readonly request: Requester) {}
+
+  list(query?: PageQuery & IssueFilters): Promise<IssuePage> {
+    return this.request({ method: 'GET', path: '/issues', query: { ...query } });
+  }
+
+  /** Every issue matching `filters`, across every page, as an async iterator. */
+  listAll(filters?: IssueFilters): AsyncIterable<Issue> {
+    return paginate((page) => this.list({ ...filters, page }));
+  }
+
+  /**
+   * The issue, its event history, every finding that has evidenced it across
+   * runs, and its comments — the view an auditor reads.
+   */
+  get(id: string): Promise<IssueDetail> {
+    return this.request({ method: 'GET', path: `/issues/${encodeURIComponent(id)}` });
+  }
+
+  /**
+   * Opens an issue by hand, fingerprinted like a finding so a later scan meets it.
+   *
+   * @throws {SecureportError} `conflict` (duplicate fingerprint) or `not_found` (`targetId`).
+   */
+  create(input: NewIssue): Promise<Issue> {
+    return this.request({ method: 'POST', path: '/issues', body: input });
+  }
+
+  update(id: string, patch: IssuePatch): Promise<Issue> {
+    return this.request({
+      method: 'PATCH',
+      path: `/issues/${encodeURIComponent(id)}`,
+      body: patch,
+    });
+  }
+
+  /**
+   * Adds a comment. **Returns the created comment, not the issue** — the one
+   * response-shape outlier among this resource's routes.
+   */
+  comment(id: string, input: NewIssueComment): Promise<IssueComment> {
+    return this.request({
+      method: 'POST',
+      path: `/issues/${encodeURIComponent(id)}/comments`,
+      body: input,
+    });
+  }
+
+  /**
+   * Marks an issue fixed — a claim, not a fact: a later run finding the
+   * weakness again regresses it, same as an automatic resolution.
+   *
+   * @throws {SecureportError} `conflict` if already resolved or ignored — one code, three messages; read `message` to tell them apart.
+   */
+  resolve(id: string, input?: ResolveInput): Promise<Issue> {
+    return this.request({
+      method: 'POST',
+      path: `/issues/${encodeURIComponent(id)}/resolve`,
+      body: input ?? {},
+    });
+  }
+
+  /**
+   * Suppresses an issue — keeps reconciling, drops out of every count but
+   * its own, resurfaces if detected severity rises or {@link IgnoreInput.expiresAt} passes.
+   *
+   * @throws {SecureportError} `conflict` if the issue is already ignored.
+   */
+  ignore(id: string, input: IgnoreInput): Promise<Issue> {
+    return this.request({
+      method: 'POST',
+      path: `/issues/${encodeURIComponent(id)}/ignore`,
+      body: input,
+    });
+  }
+
+  /**
+   * Lifts a suppression by hand — returns to `open`, the same state
+   * reconciliation restores on expiry or a severity rise.
+   *
+   * @throws {SecureportError} `conflict` if the issue is not ignored.
+   */
+  unignore(id: string): Promise<Issue> {
+    return this.request({ method: 'POST', path: `/issues/${encodeURIComponent(id)}/unignore` });
+  }
+
+  /**
+   * Merges `duplicateId` into `survivorId` (never the reverse) — nothing is
+   * rewritten; `duplicateId`'s evidence attaches to `survivorId`, which inherits the earlier `firstSeen`, and `duplicateId` becomes `ignored: duplicate`.
+   *
+   * @returns The surviving issue (`survivorId`).
+   * @throws {SecureportError} `conflict` if the two issues cannot be merged.
+   */
+  merge(survivorId: string, duplicateId: string): Promise<Issue> {
+    return this.request({
+      method: 'POST',
+      path: `/issues/${encodeURIComponent(survivorId)}/merge/${encodeURIComponent(duplicateId)}`,
+    });
+  }
+}

package/src/resources/reports.ts

@@ -0,0 +1,104 @@
+import type { RawRequester } from '../client.js';
+import type { Severity } from './issues.js';
+
+/** Which of the five report templates to render. */
+export type ReportKind = 'pen' | 'vap' | 'exec' | 'attest' | 'retest';
+
+/**
+ * The formats an API key may request.
+ *
+ * `pdf` and `html` exist on the wire but are refused with `forbidden` for
+ * any machine credential — those are documents requested from the dashboard
+ * by a signed-in user, matching the API-key boundary `@secureport/cli`'s
+ * hosted mode already settled. Restricted to this set at the type level so a
+ * caller cannot even construct the request; {@link ReportsResource.request}
+ * backs it with a runtime check for a JS consumer with no type checker.
+ */
+export type ReportFormat = 'json' | 'markdown' | 'csv' | 'sarif';
+
+/**
+ * How much evidence a document prints. **Has no effect on `json`, `csv` or
+ * `sarif`** — those formats carry what they carry, and a consumer filters;
+ * only `markdown` reads this.
+ */
+export type EvidenceVerbosity = 'none' | 'summary' | 'full';
+
+export interface ReportRequest {
+  readonly kind: ReportKind;
+  readonly format: ReportFormat;
+  readonly title?: string;
+  readonly preparedFor?: string;
+  readonly coverPage?: boolean;
+  readonly tableOfContents?: boolean;
+
+  /**
+   * Rows below this severity are dropped from the document. **The counts
+   * never move** — `outstanding`, the exposure score and the breach count
+   * describe the target, not the document, so the floor only removes rows;
+   * the document states how many it removed.
+   */
+  readonly severityFloor?: Severity;
+
+  /**
+   * Whether resolved issues are still listed. Omitting evidence of
+   * remediation only understates the good news, never the risk, so unlike
+   * {@link ReportRequest.severityFloor} this needs no disclosure in the document.
+   *
+   * @defaultValue true
+   */
+  readonly includeResolved?: boolean;
+
+  /** @defaultValue 'summary' */
+  readonly evidenceVerbosity?: EvidenceVerbosity;
+}
+
+const MACHINE_FORMATS = new Set<ReportFormat>(['json', 'markdown', 'csv', 'sarif']);
+
+/**
+ * Reports — the one resource whose response is never JSON. Every format
+ * `request` accepts is a raw, streamed body (`text/csv`,
+ * `application/sarif+json`, plain `application/json` text, …), so this
+ * resource is built on {@link SecureportClient.requestRaw} rather than the
+ * usual `request<T>()`, and hands the `Response` itself back to the caller
+ * to read as text, parse, or stream to a file.
+ */
+export class ReportsResource {
+  constructor(private readonly requestRaw: RawRequester) {}
+
+  /**
+   * Renders a run into a report and streams it back. **Nothing is stored on
+   * the API side** — the bytes are produced from the run's snapshot on
+   * demand and exist only in this response; call this again for the same
+   * run and it renders again from whatever the run's snapshot is by then.
+   *
+   * **A failure partway through the stream cannot become an HTTP status.**
+   * The status and headers this method's `Response` carries are whatever was
+   * sent before the first byte of the body; nothing that goes wrong later in
+   * the stream can change them, so a truncated document looks identical to a
+   * complete one at this layer. Verify the body's own shape — that a JSON or
+   * SARIF document parses, that a CSV has the trailer row it expects — if a
+   * caller needs to be sure nothing was cut short.
+   *
+   * @throws {Error} synchronously, before any request is made, if
+   * `input.format` is `'pdf'` or `'html'` — this method exists only for
+   * `'json' | 'csv' | 'sarif' | 'markdown'`; a caller bypassing the type
+   * (plain JS, no type checker) is told so without spending a round trip.
+   * @throws {SecureportError} `conflict` if the run has not been reconciled
+   * — still running, or ended `failed`; `forbidden` should be unreachable
+   * given the format check above, but is still what the API itself would
+   * answer for `pdf`/`html`.
+   */
+  request(runId: string, input: ReportRequest): Promise<Response> {
+    if (!MACHINE_FORMATS.has(input.format)) {
+      throw new Error(
+        `'${input.format}' reports are requested from the dashboard by a signed-in user — an ` +
+          'API key can export json, csv, sarif or markdown.',
+      );
+    }
+    return this.requestRaw({
+      method: 'POST',
+      path: `/runs/${encodeURIComponent(runId)}/reports`,
+      body: input,
+    });
+  }
+}