surfscan 0.0.0-stage → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,294 @@
+type Severity = 'high' | 'medium' | 'low' | 'info';
+/** Highest first. */
+declare const SEVERITIES: readonly Severity[];
+declare const SEVERITY_RANK: Record<Severity, number>;
+declare function isSeverity(value: unknown): value is Severity;
+interface Finding {
+    ruleId: string;
+    severity: Severity;
+    /** What was found. Must never contain a full secret value. */
+    message: string;
+    /** Path relative to the scan root, always with forward slashes. */
+    file: string;
+    /** 1-based. 0 means the finding applies to the whole file. */
+    line: number;
+    /** 1-based. */
+    column?: number;
+    /** How to fix it. */
+    fix: string;
+}
+interface SurfscanConfig {
+    /** Rule IDs to skip. */
+    ignore: string[];
+    /** Globs (relative to the scan root) to exclude from discovery. */
+    ignorePaths: string[];
+    deps: {
+        minAgeDays: number;
+        trustedPackages: string[];
+    };
+}
+/**
+ * Read-only access to the project being scanned. Implemented for Node in
+ * `node-provider.ts`; a browser demo or test can supply an in-memory one.
+ */
+interface SourceProvider {
+    /** List files matching the globs, relative to the root, with forward slashes. */
+    list(patterns: string[], ignore: string[]): Promise<string[]>;
+    /** Read a file relative to the root. Resolves to undefined if it does not exist. */
+    read(path: string, opts?: {
+        maxBytes?: number;
+    }): Promise<string | undefined>;
+    /** Links matched since the last call that were not scanned. Each is returned once. */
+    takeSkippedLinks?(): string[];
+}
+interface SourceFile {
+    /** Relative to the scan root, forward slashes. */
+    path: string;
+    content: string;
+}
+interface ScanContext {
+    files: SourceFile[];
+    config: SurfscanConfig;
+    provider: SourceProvider;
+    /** Scanner-specific options (for example `offline` for deps). */
+    options: Readonly<Record<string, unknown>>;
+    /**
+     * Report a non-fatal problem, such as an unreadable file or a network failure.
+     * Pass `incomplete: true` when the problem meant a check could not run, so
+     * the result cannot be read as "nothing found".
+     */
+    warn(message: string, opts?: {
+        incomplete?: boolean;
+    }): void;
+}
+interface Rule {
+    id: string;
+    severity: Severity;
+    title: string;
+    check(context: ScanContext): Finding[] | Promise<Finding[]>;
+}
+interface Scanner {
+    name: string;
+    /** Ordered high to low severity. */
+    rules: Rule[];
+    findTargets(provider: SourceProvider, config: SurfscanConfig): Promise<string[]>;
+    /** Read limit for this scanner's files, when they are routinely larger than the default. */
+    maxFileBytes?: number;
+}
+interface ScanResult {
+    findings: Finding[];
+    warnings: string[];
+    /** True when at least one check could not run (for example the registry was unreachable). */
+    incomplete: boolean;
+}
+
+/** Paths never scanned, in addition to config.ignorePaths. */
+declare const DEFAULT_IGNORE_PATHS: string[];
+interface RunOptions {
+    provider: SourceProvider;
+    config: SurfscanConfig;
+    /** Scanner-specific options, passed through to rules as `context.options`. */
+    options?: Record<string, unknown>;
+}
+declare function compareFindings(a: Finding, b: Finding): number;
+declare function sortFindings(findings: Finding[]): Finding[];
+/** Discover target files for a scanner, honouring default and configured ignores. */
+declare function listTargets(provider: SourceProvider, config: SurfscanConfig, patterns: string[], extraIgnore?: string[]): Promise<string[]>;
+declare function runScanner(scanner: Scanner, opts: RunOptions): Promise<ScanResult>;
+declare function runScanners(scanners: Scanner[], opts: RunOptions): Promise<ScanResult>;
+declare function summarize(findings: Finding[]): Record<Severity, number>;
+/** True when at least one finding is at or above the threshold. */
+declare function hasFailures(findings: Finding[], failOn: Severity): boolean;
+
+declare const CONFIG_FILE_NAME = "surfscan.json";
+declare const DEFAULT_CONFIG: SurfscanConfig;
+declare class ConfigError extends Error {
+    constructor(message: string);
+}
+/** Validate a parsed config object and merge it over the defaults. */
+declare function validateConfig(raw: unknown, source?: string): SurfscanConfig;
+/** Parse and validate the text of a surfscan.json file. */
+declare function parseConfig(text: string, source?: string): SurfscanConfig;
+/**
+ * Load a config file through the given reader. Resolves to the defaults when
+ * the file does not exist and `required` is false.
+ */
+declare function loadConfig(read: (path: string) => Promise<string | undefined>, path: string, required: boolean): Promise<SurfscanConfig>;
+
+/** Read-only file access rooted at a directory on disk. */
+declare function createNodeProvider(root: string): SourceProvider;
+
+/**
+ * Patterns for well-known secret formats. Used by the report layer as a last
+ * line of defence against printing a secret, and by the keys scanner.
+ */
+interface SecretPattern {
+    name: string;
+    regex: RegExp;
+}
+declare const SECRET_PATTERNS: readonly SecretPattern[];
+/** Mask a secret value: first 4 characters, then "...". */
+declare function maskSecret(value: string): string;
+/** Replace anything that looks like a secret in text about to be printed. */
+declare function redactSecrets(text: string): string;
+
+interface TextOptions {
+    color: boolean;
+    /** A check could not run; say so under the summary. */
+    incomplete?: boolean;
+}
+declare function summaryLine(findings: Finding[]): string;
+/** Findings must already be sorted. */
+declare function formatText(findings: Finding[], opts: TextOptions): string;
+
+declare const JSON_REPORT_VERSION = 1;
+interface JsonReport {
+    version: number;
+    summary: Record<Severity, number>;
+    /** False when a check could not run, so an empty `findings` does not mean clean. */
+    complete: boolean;
+    warnings: string[];
+    findings: Finding[];
+}
+interface ReportMeta {
+    warnings?: string[];
+    incomplete?: boolean;
+}
+declare function toJsonReport(findings: Finding[], meta?: ReportMeta): JsonReport;
+declare function formatJson(findings: Finding[], meta?: ReportMeta): string;
+
+/** Make text safe to print on a terminal: escape control and invisible characters. */
+declare function escapeUnsafe(text: string): string;
+/** Mask secrets in every text field of a finding. Applied to all output formats. */
+declare function redactFinding(f: Finding): Finding;
+
+/** Agent instruction files, at any depth so monorepo packages are covered. */
+declare const RULES_TARGETS: string[];
+declare const rules$4: Rule[];
+declare const rulesScanner: Scanner;
+
+/** A match inside some text, before it is mapped to a file position. */
+interface TextMatch {
+    index: number;
+    /** Short human-readable description of what matched. */
+    detail: string;
+}
+
+declare const KEYS_TARGETS: string[];
+declare const rules$3: Rule[];
+declare const keysScanner: Scanner;
+
+/** A setting found in an agent config, with the line it is on. */
+interface Located<T> {
+    value: T;
+    line: number;
+}
+/** One auto-approve entry, normalized across agents. */
+interface AllowEntry {
+    /** The entry as written, for messages. */
+    raw: string;
+    line: number;
+    /** 'shell' covers Bash, PowerShell and similar command tools. */
+    kind: 'shell' | 'mcp' | 'other';
+    /** Shell: the command pattern (`*` is a wildcard). Undefined means every command. */
+    command?: string;
+    /** MCP: server name, and tool pattern (undefined means every tool). */
+    mcpServer?: string;
+    mcpTool?: string;
+}
+/** What an agent config auto-approves, in agent-neutral terms. */
+interface ApprovalSettings {
+    agent: string;
+    file: string;
+    /** Modes or flags that skip permission prompts entirely. */
+    bypass: Array<Located<string>>;
+    allow: AllowEntry[];
+    /** Modes that auto-approve some actions, such as file edits. */
+    partial: Array<Located<string>>;
+    /** Settings that auto-approve every project MCP server. */
+    allMcpServers: Array<Located<string>>;
+}
+/**
+ * Reads one agent's config format. Add an adapter per agent; rules only see
+ * ApprovalSettings.
+ */
+interface ApprovalAdapter {
+    agent: string;
+    /** Globs relative to the project root. */
+    targets: string[];
+    /** True when a discovered path belongs to this adapter. */
+    matches(path: string): boolean;
+    /** Returns undefined when the file holds nothing to check. Throws on parse errors. */
+    parse(file: SourceFile): ApprovalSettings | undefined;
+}
+
+/** Registered agent adapters. Add new agents here. */
+declare const adapters: ApprovalAdapter[];
+declare const rules$2: Rule[];
+declare const approvalsScanner: Scanner;
+
+declare const MCP_TARGETS: string[];
+declare const rules$1: Rule[];
+declare const mcpScanner: Scanner;
+
+declare const LOCK_FILE_PATH = ".surfscan/mcp.lock.json";
+interface McpTool {
+    name: string;
+    /** The tool as exported: description, inputSchema and so on. */
+    definition: Record<string, unknown>;
+}
+type ToolList = Record<string, McpTool[]>;
+/** Options read from `ScanContext.options`. */
+interface ToolSource {
+    /** Where the list came from, shown in findings. Omitted when read from running servers. */
+    file?: string;
+    /** The text of the file, used to find line numbers. */
+    content?: string;
+    tools: ToolList;
+}
+type LockFile = {
+    version: 1;
+    servers: Record<string, Record<string, string>>;
+};
+/**
+ * Accepts a `tools/list` result (`{ "tools": [...] }`, optionally inside a
+ * JSON-RPC `result`), a bare array, or `{ "servers": { "<name>": <either> } }`.
+ */
+declare function parseToolList(text: string): ToolList;
+declare function buildLock(tools: ToolList): Promise<LockFile>;
+
+type FetchLike = (url: string, init?: {
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+}>;
+
+declare const DEPS_TARGETS: string[];
+/** Options read from `ScanContext.options`. */
+interface DepsOptions {
+    offline?: boolean;
+    fetch?: FetchLike;
+    registryUrl?: string;
+    downloadsUrl?: string;
+}
+declare const rules: Rule[];
+declare const depsScanner: Scanner;
+
+interface InvisibleMatch extends TextMatch {
+    codePoints: number[];
+}
+/** One match per line, listing the distinct invisible characters found on it. */
+declare function findInvisibleChars(text: string): InvisibleMatch[];
+declare function findHiddenContent(text: string): TextMatch[];
+declare function findPipeToShell(text: string): TextMatch[];
+declare function findCredentialAccess(text: string): TextMatch[];
+declare function findInstructionOverride(text: string): TextMatch[];
+declare function findEncodedBlocks(text: string): TextMatch[];
+declare function findUnpinnedInstalls(text: string): TextMatch[];
+declare function findRemoteInstructions(text: string): TextMatch[];
+
+export { CONFIG_FILE_NAME, ConfigError, DEFAULT_CONFIG, DEFAULT_IGNORE_PATHS, DEPS_TARGETS, JSON_REPORT_VERSION, KEYS_TARGETS, LOCK_FILE_PATH, MCP_TARGETS, RULES_TARGETS, SECRET_PATTERNS, SEVERITIES, SEVERITY_RANK, adapters as approvalAdapters, rules$2 as approvalRules, approvalsScanner, buildLock, compareFindings, createNodeProvider, rules as depsRules, depsScanner, escapeUnsafe, findCredentialAccess, findEncodedBlocks, findHiddenContent, findInstructionOverride, findInvisibleChars, findPipeToShell, findRemoteInstructions, findUnpinnedInstalls, formatJson, formatText, hasFailures, rules$4 as instructionRules, isSeverity, rules$3 as keyRules, keysScanner, listTargets, loadConfig, maskSecret, rules$1 as mcpRules, mcpScanner, parseConfig, parseToolList, redactFinding, redactSecrets, rulesScanner, runScanner, runScanners, sortFindings, summarize, summaryLine, toJsonReport, validateConfig };
+export type { AllowEntry, ApprovalAdapter, ApprovalSettings, DepsOptions, FetchLike, Finding, JsonReport, LockFile, McpTool, Rule, RunOptions, ScanContext, ScanResult, Scanner, Severity, SourceFile, SourceProvider, SurfscanConfig, TextOptions, ToolList, ToolSource };

package/dist/index.js

@@ -0,0 +1,113 @@
+import {
+  CONFIG_FILE_NAME,
+  ConfigError,
+  DEFAULT_CONFIG,
+  DEFAULT_IGNORE_PATHS,
+  DEPS_TARGETS,
+  JSON_REPORT_VERSION,
+  KEYS_TARGETS,
+  LOCK_FILE_PATH,
+  MCP_TARGETS,
+  RULES_TARGETS,
+  SECRET_PATTERNS,
+  SEVERITIES,
+  SEVERITY_RANK,
+  adapters,
+  approvalsScanner,
+  buildLock,
+  compareFindings,
+  createNodeProvider,
+  depsScanner,
+  escapeUnsafe,
+  findCredentialAccess,
+  findEncodedBlocks,
+  findHiddenContent,
+  findInstructionOverride,
+  findInvisibleChars,
+  findPipeToShell,
+  findRemoteInstructions,
+  findUnpinnedInstalls,
+  formatJson,
+  formatText,
+  hasFailures,
+  isSeverity,
+  keysScanner,
+  listTargets,
+  loadConfig,
+  maskSecret,
+  mcpScanner,
+  parseConfig,
+  parseToolList,
+  redactFinding,
+  redactSecrets,
+  rules,
+  rules2,
+  rules3,
+  rules4,
+  rules5,
+  rulesScanner,
+  runScanner,
+  runScanners,
+  sortFindings,
+  summarize,
+  summaryLine,
+  toJsonReport,
+  validateConfig
+} from "./chunk-MJKZGRUS.js";
+export {
+  CONFIG_FILE_NAME,
+  ConfigError,
+  DEFAULT_CONFIG,
+  DEFAULT_IGNORE_PATHS,
+  DEPS_TARGETS,
+  JSON_REPORT_VERSION,
+  KEYS_TARGETS,
+  LOCK_FILE_PATH,
+  MCP_TARGETS,
+  RULES_TARGETS,
+  SECRET_PATTERNS,
+  SEVERITIES,
+  SEVERITY_RANK,
+  adapters as approvalAdapters,
+  rules3 as approvalRules,
+  approvalsScanner,
+  buildLock,
+  compareFindings,
+  createNodeProvider,
+  rules5 as depsRules,
+  depsScanner,
+  escapeUnsafe,
+  findCredentialAccess,
+  findEncodedBlocks,
+  findHiddenContent,
+  findInstructionOverride,
+  findInvisibleChars,
+  findPipeToShell,
+  findRemoteInstructions,
+  findUnpinnedInstalls,
+  formatJson,
+  formatText,
+  hasFailures,
+  rules as instructionRules,
+  isSeverity,
+  rules2 as keyRules,
+  keysScanner,
+  listTargets,
+  loadConfig,
+  maskSecret,
+  rules4 as mcpRules,
+  mcpScanner,
+  parseConfig,
+  parseToolList,
+  redactFinding,
+  redactSecrets,
+  rulesScanner,
+  runScanner,
+  runScanners,
+  sortFindings,
+  summarize,
+  summaryLine,
+  toJsonReport,
+  validateConfig
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}