verimu 0.0.21 → 0.0.22

package/dist/index.d.ts

@@ -271,6 +271,12 @@ interface VerimuConfig {
     numContextLines?: number;
     /** Optional group name to associate this project with others in the dashboard */
     groupName?: string;
+    /** Optional explicit project name to use for backend upsert/upload */
+    uploadProjectName?: string;
+    /** Optional repository URL to associate with this project in backend */
+    repositoryUrl?: string;
+    /** Optional source platform label (e.g., gitlab, github, bitbucket) */
+    platform?: CiProvider;
 }
 /** Input for the pure `generateSbom()` function */
 interface GenerateSbomInput {
@@ -520,6 +526,489 @@ declare function shouldFailCi(report: VerimuReport, threshold: Severity): boolea
  */
 declare function printReport(report: VerimuReport): void;
 
+/**
+ * Types for the GitLab integration — remote scanning of self-hosted
+ * or cloud GitLab instances.
+ */
+
+/** GitLab project as returned by /api/v4/projects */
+interface GitLabProject {
+    id: number;
+    name: string;
+    name_with_namespace: string;
+    path: string;
+    path_with_namespace: string;
+    description: string | null;
+    http_url_to_repo: string;
+    ssh_url_to_repo: string;
+    web_url: string;
+    default_branch: string;
+    archived: boolean;
+    empty_repo: boolean;
+    visibility: 'private' | 'internal' | 'public';
+    last_activity_at: string;
+    namespace: {
+        id: number;
+        name: string;
+        path: string;
+        kind: 'group' | 'user';
+        full_path: string;
+    };
+}
+/** GitLab group as returned by /api/v4/groups */
+interface GitLabGroup {
+    id: number;
+    name: string;
+    path: string;
+    full_path: string;
+    description: string | null;
+    web_url: string;
+    parent_id: number | null;
+}
+/** Configuration for a GitLab-wide scan */
+interface GitLabScanConfig {
+    /** GitLab instance base URL (e.g., https://git.solve.ch) */
+    url: string;
+    /** Personal access token or deploy token */
+    token: string;
+    /** Only scan repos in these groups (by path or ID). Empty = all accessible repos. */
+    groups?: string[];
+    /** Exclude repos matching these patterns (path_with_namespace glob) */
+    excludePatterns?: string[];
+    /** Skip archived repositories (default: true) */
+    excludeArchived?: boolean;
+    /** Skip empty repositories (default: true) */
+    excludeEmpty?: boolean;
+    /** Skip forked repositories (default: false) */
+    excludeForks?: boolean;
+    /** Maximum number of repos to scan (for testing) */
+    maxRepos?: number;
+    /** Branch to clone (default: each repo's default branch) */
+    branch?: string;
+    /** Where to write the HTML report */
+    htmlOutput?: string;
+    /** Where to write the JSON aggregate report */
+    jsonOutput?: string;
+    /** Skip CVE checking (just discover dependencies) */
+    skipCveCheck?: boolean;
+    /** Verimu API key for platform upload */
+    apiKey?: string;
+    /** Verimu API base URL */
+    apiBaseUrl?: string;
+    /** Group name for Verimu platform */
+    groupName?: string;
+    /** Maximum concurrent clone operations */
+    concurrency?: number;
+}
+/** Result of scanning a single GitLab repo */
+interface GitLabRepoScanResult {
+    /** GitLab project metadata */
+    project: GitLabProject;
+    /** Verimu scan reports (one per discovered project in the repo) */
+    reports: VerimuReport[];
+    /** Whether any lockfile was found in the repo */
+    hasLockfile: boolean;
+    /** Error message if scan failed */
+    error?: string;
+    /** Time taken for this repo (clone + scan + cleanup) in ms */
+    durationMs: number;
+}
+/** Aggregate result of scanning all GitLab repos */
+interface GitLabScanResult {
+    /** GitLab instance URL */
+    instanceUrl: string;
+    /** Total repositories discovered on the instance */
+    totalReposDiscovered: number;
+    /** Repos that were scanned (had lockfiles) */
+    scannedRepos: GitLabRepoScanResult[];
+    /** Repos skipped (no lockfile, archived, empty, excluded) */
+    skippedRepos: Array<{
+        project: GitLabProject;
+        reason: string;
+    }>;
+    /** Repos that failed to scan */
+    failedRepos: Array<{
+        project: GitLabProject;
+        error: string;
+    }>;
+    /** Aggregate vulnerability summary across all repos */
+    summary: {
+        totalRepos: number;
+        reposWithVulnerabilities: number;
+        totalDependencies: number;
+        totalVulnerabilities: number;
+        critical: number;
+        high: number;
+        medium: number;
+        low: number;
+        exploitedInWild: number;
+        ecosystemBreakdown: Record<string, number>;
+    };
+    /** Top vulnerabilities by severity (deduped across repos) */
+    topVulnerabilities: Array<{
+        id: string;
+        severity: Severity;
+        summary: string;
+        affectedRepos: string[];
+        fixedVersion?: string;
+        exploitedInWild: boolean;
+    }>;
+    /** Scan timestamp */
+    scannedAt: string;
+    /** Total scan duration in ms */
+    durationMs: number;
+}
+
+/**
+ * GitLab API client for listing and cloning repositories.
+ *
+ * Designed for self-hosted GitLab instances (e.g., git.solve.ch)
+ * but works with gitlab.com as well.
+ */
+
+declare class GitLabClient {
+    private baseUrl;
+    private token;
+    private apiUrl;
+    constructor(baseUrl: string, token: string);
+    /**
+     * Lists all accessible projects, paginated.
+     * Returns all pages concatenated.
+     */
+    listAllProjects(options?: {
+        archived?: boolean;
+        perPage?: number;
+        maxPages?: number;
+    }): Promise<GitLabProject[]>;
+    /**
+     * Lists projects within a specific group (and its subgroups).
+     */
+    listGroupProjects(groupPath: string, options?: {
+        includeSubgroups?: boolean;
+        perPage?: number;
+    }): Promise<GitLabProject[]>;
+    /**
+     * Lists all groups accessible to the token.
+     */
+    listGroups(): Promise<GitLabGroup[]>;
+    /**
+     * Shallow-clones a repo into a temporary directory.
+     * Returns the path to the cloned repo.
+     *
+     * Uses HTTPS with token auth embedded in the URL
+     * (works for self-hosted GitLab with private-token).
+     */
+    cloneToTemp(project: GitLabProject, branch?: string): string;
+    /**
+     * Removes a temporary clone directory.
+     */
+    cleanupTemp(tempDir: string): void;
+    /**
+     * Builds an authenticated HTTPS URL for git clone.
+     * Embeds the token as oauth2 password.
+     */
+    private buildAuthUrl;
+    /**
+     * Makes an authenticated GET request to the GitLab API.
+     */
+    private fetch;
+}
+
+/**
+ * GitLab scan orchestrator — clones each repo, scans with Verimu,
+ * aggregates results, and generates the report.
+ *
+ * Usage:
+ *   const orchestrator = new GitLabOrchestrator();
+ *   const result = await orchestrator.scanInstance(config);
+ */
+
+declare class GitLabOrchestrator {
+    private discovery;
+    /**
+     * Scans all accessible repos on a GitLab instance.
+     */
+    scanInstance(config: GitLabScanConfig): Promise<GitLabScanResult>;
+    private filterProjects;
+    private matchGlob;
+    private aggregate;
+    private printSummary;
+}
+
+/**
+ * HTML report generator for GitLab-wide scans.
+ *
+ * Generates a self-contained, single-file HTML report that can be
+ * attached to an email or opened in any browser. No external deps.
+ */
+
+declare class HtmlReporter {
+    readonly name = "html";
+    generate(result: GitLabScanResult): string;
+    private header;
+    private summaryCards;
+    private severityChart;
+    private topVulnerabilities;
+    private repoBreakdown;
+    private ecosystemBreakdown;
+    private craTimeline;
+    private footer;
+    private styles;
+    private escapeHtml;
+    private sevClass;
+}
+
+/**
+ * Types for the GitHub integration — remote scanning of GitHub.com
+ * or GitHub Enterprise Server (GHES) instances.
+ */
+
+/** GitHub repository as returned by the REST API */
+interface GitHubRepo {
+    id: number;
+    name: string;
+    full_name: string;
+    private: boolean;
+    fork: boolean;
+    archived: boolean;
+    default_branch: string;
+    html_url: string;
+    clone_url: string;
+    owner: {
+        login: string;
+        type: 'User' | 'Organization';
+    };
+}
+/** GitHub user/org info as returned by GET /users/{username} */
+interface GitHubUser {
+    login: string;
+    id: number;
+    type: 'User' | 'Organization';
+    name: string | null;
+    public_repos: number;
+}
+/** Configuration for a GitHub-wide scan */
+interface GitHubScanConfig {
+    /** GitHub base URL (default: https://github.com, supports GHES) */
+    baseUrl: string;
+    /** Org/user profile to enumerate repos (URL or handle) */
+    profile: string;
+    /** Personal access token or fine-grained token */
+    token?: string;
+    /** For user profiles, list only owner repositories (default: false) */
+    ownerOnly?: boolean;
+    /** Exclude forked repositories (default: false) */
+    excludeForks?: boolean;
+    /** Exclude archived repositories (default: true) */
+    excludeArchived?: boolean;
+    /** Maximum number of repos to scan */
+    maxRepos?: number;
+    /** Branch to clone (default: each repo's default branch) */
+    branch?: string;
+    /** Where to write the HTML report */
+    htmlOutput?: string;
+    /** Where to write the JSON aggregate report */
+    jsonOutput?: string;
+    /** Skip CVE checking (just discover dependencies) */
+    skipCveCheck?: boolean;
+    /** Verimu API key for platform upload */
+    apiKey?: string;
+    /** Verimu API base URL */
+    apiBaseUrl?: string;
+    /** Group name for Verimu platform */
+    groupName?: string;
+}
+/** Result of scanning a single GitHub repo */
+interface GitHubRepoScanResult {
+    /** GitHub repo metadata */
+    repo: GitHubRepo;
+    /** Verimu scan reports (one per discovered project in the repo) */
+    reports: VerimuReport[];
+    /** Whether any lockfile was found in the repo */
+    hasLockfile: boolean;
+    /** Error message if scan failed */
+    error?: string;
+    /** Time taken for this repo (clone + scan + cleanup) in ms */
+    durationMs: number;
+}
+/** Aggregate result of scanning all GitHub repos */
+interface GitHubScanResult {
+    /** GitHub base URL */
+    instanceUrl: string;
+    /** Profile that was scanned (org or user login) */
+    profile: string;
+    /** Owner type that was resolved */
+    profileType: 'org' | 'user';
+    /** Total repositories discovered */
+    totalReposDiscovered: number;
+    /** Repos that were scanned (had lockfiles) */
+    scannedRepos: GitHubRepoScanResult[];
+    /** Repos skipped (no lockfile, archived, forked, excluded) */
+    skippedRepos: Array<{
+        repo: GitHubRepo;
+        reason: string;
+    }>;
+    /** Repos that failed to scan */
+    failedRepos: Array<{
+        repo: GitHubRepo;
+        error: string;
+    }>;
+    /** Aggregate vulnerability summary across all repos */
+    summary: {
+        totalRepos: number;
+        reposWithVulnerabilities: number;
+        totalDependencies: number;
+        totalVulnerabilities: number;
+        critical: number;
+        high: number;
+        medium: number;
+        low: number;
+        exploitedInWild: number;
+        ecosystemBreakdown: Record<string, number>;
+    };
+    /** Top vulnerabilities by severity (deduped across repos) */
+    topVulnerabilities: Array<{
+        id: string;
+        severity: Severity;
+        summary: string;
+        affectedRepos: string[];
+        fixedVersion?: string;
+        exploitedInWild: boolean;
+    }>;
+    /** Scan timestamp */
+    scannedAt: string;
+    /** Total scan duration in ms */
+    durationMs: number;
+}
+
+/**
+ * GitHub API client for listing and cloning repositories.
+ *
+ * Supports github.com and GitHub Enterprise Server (GHES).
+ * Handles both authenticated (5,000 req/h) and unauthenticated (60 req/h)
+ * rate limits, with automatic wait-and-retry on transient errors.
+ */
+
+interface RateLimitInfo {
+    limit: number;
+    remaining: number;
+    resetAt: Date;
+    used: number;
+}
+interface ParsedProfile {
+    /** The login/handle extracted from the URL or raw input */
+    login: string;
+}
+/**
+ * Parses a GitHub profile input which can be:
+ *  - A full URL: https://github.com/octokit
+ *  - A URL with trailing slash/params: https://github.com/octokit/?tab=repos
+ *  - A bare handle: octokit
+ */
+declare function parseProfile(input: string, baseUrl: string): ParsedProfile;
+declare class GitHubClient {
+    private baseUrl;
+    private apiUrl;
+    private token?;
+    private lastRateLimit?;
+    constructor(baseUrl: string, token?: string);
+    /**
+     * Determines whether a login is a User or Organization by
+     * calling GET /users/{username} and reading the `type` field.
+     */
+    detectOwnerType(login: string): Promise<'org' | 'user'>;
+    /**
+     * Lists repositories for an organization.
+     * Uses GET /orgs/{org}/repos with pagination.
+     */
+    listOrgRepos(org: string): Promise<GitHubRepo[]>;
+    /**
+     * Lists repositories for a user.
+     *
+      * - Without token: GET /users/{username}/repos
+      *   - default: type=all
+      *   - ownerOnly: type=owner
+     * - With token for own user: GET /user/repos filtered by owner login
+     *   (includes private repos the token can see)
+      * - With token for other user: GET /users/{username}/repos
+     *   (only public repos visible)
+     */
+    listUserRepos(login: string, ownerOnly?: boolean): Promise<GitHubRepo[]>;
+    /**
+     * Lists repos based on resolved owner type.
+     */
+    listRepos(login: string, ownerType: 'org' | 'user', options?: {
+        ownerOnly?: boolean;
+    }): Promise<GitHubRepo[]>;
+    /**
+     * Shallow-clones a repo into a temporary directory.
+     * Returns the path to the cloned repo.
+     *
+     * Uses HTTPS with token auth embedded in the URL (when token is available).
+     */
+    cloneToTemp(repo: GitHubRepo, branch?: string): string;
+    /**
+     * Removes a temporary clone directory.
+     */
+    cleanupTemp(tempDir: string): void;
+    /** Returns the last observed rate limit info, if any. */
+    getRateLimit(): RateLimitInfo | undefined;
+    /**
+     * Returns the hourly rate limit for this client configuration.
+     * - Unauthenticated: 60 requests/hour
+     * - Authenticated (PAT/OAuth): 5,000 requests/hour
+     */
+    getExpectedRateLimit(): number;
+    /**
+     * Paginated GET — fetches all pages of a list endpoint.
+     * GitHub uses `per_page` (max 100) and `page` parameters.
+     */
+    private paginate;
+    /**
+     * Builds an authenticated HTTPS URL for git clone.
+     * Embeds the token as a password with "x-access-token" user.
+     */
+    private buildAuthUrl;
+    /**
+     * Makes an authenticated GET request to the GitHub API.
+     *
+     * Rate limit handling:
+     * - Reads X-RateLimit-Remaining and X-RateLimit-Reset headers
+     * - If remaining is 0, waits until the reset time or throws with actionable message
+     * - Retries on transient 502/503/504 with exponential backoff (up to 3 retries)
+     * - Returns 403/429 rate limit errors with reset time information
+     */
+    private fetch;
+    /**
+     * Updates internal rate limit tracker from response headers.
+     */
+    private updateRateLimit;
+    private sleep;
+}
+
+/**
+ * GitHub scan orchestrator — clones each repo, scans with Verimu,
+ * aggregates results, and generates the report.
+ *
+ *
+ * Usage:
+ *   const orchestrator = new GitHubOrchestrator();
+ *   const result = await orchestrator.scanProfile(config);
+ */
+
+declare class GitHubOrchestrator {
+    private discovery;
+    /**
+     * Scans all repos for a GitHub profile (org or user).
+     */
+    scanProfile(config: GitHubScanConfig): Promise<GitHubScanResult>;
+    private filterRepos;
+    private getUploadProjectName;
+    private getAutoGroupName;
+    private aggregate;
+    private printSummary;
+}
+
 /** Base error for all Verimu errors */
 declare class VerimuError extends Error {
     readonly code: string;
@@ -1511,4 +2000,4 @@ declare class UsageContextEngine {
     private normalizePositiveInt;
 }
 
-export { ApiKeyRequiredError, CargoScanner, type CiProvider, ComposerScanner, ConsoleReporter, CveAggregator, type CveCheckResult, CveSourceError, CycloneDxGenerator, DenoScanner, type Dependency, type Ecosystem, type GenerateSbomInput, type GenerateSbomResult, type GenerateSpdxSbomResult, type GenerateSwidTagResult, GoScanner, LockfileParseError, MavenScanner, NoLockfileError, NpmScanner, NugetScanner, OsvSource, PipScanner, PnpmScanner, RubyScanner, type Sbom, type SbomArtifacts, type SbomDependency, type SbomFormat, type SbomSource, type ScanResult, ScannerRegistry, type Severity, SpdxJsonGenerator, SwidTagGenerator, type UploadResult, type UsageContextEcosystemStatus, UsageContextEngine, type UsageContextError, type UsageContextLlmPayload, type UsageContextResult, type UsageContextStatus, type UsageContextVulnerabilityFinding, type UsageSnippet, type UsageSnippetMatchKind, VerimuApiClient, type VerimuConfig, VerimuError, type VerimuReport, type Vulnerability, type VulnerabilitySource, YarnScanner, detectSource, generateSbom, generateSbomArtifacts, generateSpdxSbom, generateSwidTag, printReport, scan, shouldFailCi, uploadToVerimu };
+export { ApiKeyRequiredError, CargoScanner, type CiProvider, ComposerScanner, ConsoleReporter, CveAggregator, type CveCheckResult, CveSourceError, CycloneDxGenerator, DenoScanner, type Dependency, type Ecosystem, type GenerateSbomInput, type GenerateSbomResult, type GenerateSpdxSbomResult, type GenerateSwidTagResult, GitHubClient, GitHubOrchestrator, type GitHubRepo, type GitHubRepoScanResult, type GitHubScanConfig, type GitHubScanResult, type GitHubUser, GitLabClient, type GitLabGroup, GitLabOrchestrator, type GitLabProject, type GitLabRepoScanResult, type GitLabScanConfig, type GitLabScanResult, GoScanner, HtmlReporter, LockfileParseError, MavenScanner, NoLockfileError, NpmScanner, NugetScanner, OsvSource, PipScanner, PnpmScanner, RubyScanner, type Sbom, type SbomArtifacts, type SbomDependency, type SbomFormat, type SbomSource, type ScanResult, ScannerRegistry, type Severity, SpdxJsonGenerator, SwidTagGenerator, type UploadResult, type UsageContextEcosystemStatus, UsageContextEngine, type UsageContextError, type UsageContextLlmPayload, type UsageContextResult, type UsageContextStatus, type UsageContextVulnerabilityFinding, type UsageSnippet, type UsageSnippetMatchKind, VerimuApiClient, type VerimuConfig, VerimuError, type VerimuReport, type Vulnerability, type VulnerabilitySource, YarnScanner, detectSource, generateSbom, generateSbomArtifacts, generateSpdxSbom, generateSwidTag, parseProfile, printReport, scan, shouldFailCi, uploadToVerimu };