@yiaany/ghostapi 0.1.6 → 0.1.8

package/dist/inventory/types.d.ts

@@ -0,0 +1,579 @@
+export declare const INVENTORY_SCHEMA_VERSION = 1;
+export declare const INVENTORY_KIND = "ghostapi.inventory";
+export declare const IMPORT_SOURCE_TYPES: readonly ["config", "ci", "gateway", "cloud"];
+export type ImportSourceType = (typeof IMPORT_SOURCE_TYPES)[number];
+export declare const TOOL_KINDS: readonly ["mcp_server", "sdk_client", "http_client"];
+export type ToolKind = (typeof TOOL_KINDS)[number];
+export declare const IDENTITY_ROLES: readonly ["service_account", "user", "workload"];
+export type IdentityRole = (typeof IDENTITY_ROLES)[number];
+export declare const SIDE_EFFECT_KINDS: readonly ["read", "create", "update", "communicate", "money_movement", "delete", "permission_change", "deployment"];
+export type SideEffectKind = (typeof SIDE_EFFECT_KINDS)[number];
+export declare const IMPACT_SEVERITIES: readonly ["low", "medium", "high", "critical"];
+export type ImpactSeverity = (typeof IMPACT_SEVERITIES)[number];
+export declare const EDGE_RELATIONS: readonly ["owns", "uses", "connects", "exposes", "permits", "requires"];
+export type EdgeRelation = (typeof EDGE_RELATIONS)[number];
+export declare const NODE_KINDS: readonly ["agent", "identity", "tool", "provider", "resource", "side_effect", "credential"];
+export type NodeKind = (typeof NODE_KINDS)[number];
+export declare const FINDING_KINDS: readonly ["orphaned_agents", "stale_unused_credentials", "excessive_permissions", "unowned_production_integrations", "agents_outside_gateway", "missing_kill_switch", "missing_evidence", "policy_drift"];
+export type FindingKind = (typeof FINDING_KINDS)[number];
+export declare const FINDING_BASIS: readonly ["evidence", "heuristic"];
+export type FindingBasis = (typeof FINDING_BASIS)[number];
+export declare const FINDING_SEVERITIES: readonly ["critical", "high", "medium", "low"];
+export type FindingSeverity = (typeof FINDING_SEVERITIES)[number];
+export declare const REMEDIATION_KINDS: readonly ["assign_owner", "reduce_scope", "revoke", "onboard_through_gateway", "create_eval"];
+export type RemediationKind = (typeof REMEDIATION_KINDS)[number];
+export declare const REMEDIATION_STATUSES: readonly ["proposed", "applied", "rejected", "expired"];
+export type RemediationStatus = (typeof REMEDIATION_STATUSES)[number];
+export declare const FRESHNESS_DEFAULT_DAYS: {
+    readonly edgeStale: 90;
+    readonly credentialStale: 90;
+    readonly evidenceFresh: 30;
+};
+export type InventoryFreshnessDays = {
+    edgeStaleDays?: number;
+    credentialStaleDays?: number;
+    evidenceFreshDays?: number;
+};
+export declare const INVENTORY_LIMITS: {
+    readonly maxStoreBytes: number;
+    readonly maxSources: 64;
+    readonly maxImports: 256;
+    readonly maxAgents: 500;
+    readonly maxTools: 500;
+    readonly maxIdentities: 500;
+    readonly maxProviders: 200;
+    readonly maxResources: 1000;
+    readonly maxSideEffects: 2000;
+    readonly maxCredentials: 500;
+    readonly maxPolicies: 100;
+    readonly maxEdges: 6000;
+    readonly maxFindings: 3000;
+    readonly maxRemediations: 1000;
+    readonly maxReferencesPerRecord: 64;
+    readonly maxScopesPerRecord: 32;
+    readonly maxCounters: 3;
+};
+export type InventoryOperatorPermission = "inventory.import" | "inventory.inspect" | "inventory.analyze" | "inventory.remediate" | "inventory.export";
+export type InventoryOperator = {
+    id: string;
+    principalId: string;
+    tenantId: string;
+    permissions: readonly InventoryOperatorPermission[];
+};
+export interface InventoryOperatorAuthorizer {
+    authenticate(identity: unknown): Promise<InventoryOperator>;
+}
+export type RecordProvenance = {
+    sourceId: string;
+    sourceType: ImportSourceType;
+    sourceName: string;
+    importedAt: string;
+    importedBy: string;
+};
+export type RecordFreshness = {
+    firstSeenAt: string;
+    lastSeenAt: string;
+};
+export type FreshnessStatus = "fresh" | "stale" | "missing";
+export type AgentRecord = {
+    schemaVersion: 1;
+    kind: "ghostapi.inventory-agent";
+    tenantId: string;
+    agentId: string;
+    name: string;
+    ownerId: string | null;
+    businessPurpose?: string;
+    model?: string;
+    runtime?: string;
+    version?: string;
+    identityIds: string[];
+    environmentIds: string[];
+    gatewayManaged: boolean;
+    killSwitchEnabled: boolean;
+    lastEvidenceAt: string | null;
+    provenance: RecordProvenance;
+    freshness: RecordFreshness;
+};
+export type ToolRecord = {
+    schemaVersion: 1;
+    tenantId: string;
+    toolId: string;
+    name: string;
+    kind: ToolKind;
+    providerId: string | null;
+    requiredScopes: string[];
+    credentialIds: string[];
+    provenance: RecordProvenance;
+    freshness: RecordFreshness;
+};
+export type IdentityRecord = {
+    schemaVersion: 1;
+    kind: "ghostapi.inventory-identity";
+    tenantId: string;
+    identityId: string;
+    principalId: string;
+    role: IdentityRole;
+    agentId: string | null;
+    toolIds: string[];
+    environmentIds: string[];
+    scopes: string[];
+    provenance: RecordProvenance;
+    freshness: RecordFreshness;
+};
+export type ProviderRecord = {
+    schemaVersion: 1;
+    kind: "ghostapi.inventory-provider";
+    tenantId: string;
+    providerId: string;
+    name: string;
+    providerType: string;
+    ownerId: string | null;
+    environmentIds: string[];
+    resourceIds: string[];
+    gatewayBound: boolean;
+    killSwitchApplied: boolean;
+    provenance: RecordProvenance;
+    freshness: RecordFreshness;
+};
+export type ResourceRecord = {
+    schemaVersion: 1;
+    kind: "ghostapi.inventory-resource";
+    tenantId: string;
+    resourceId: string;
+    providerId: string;
+    resourceType: string;
+    name: string;
+    environmentIds: string[];
+    sensitive: boolean;
+    ownerId: string | null;
+    businessPurpose?: string;
+    sideEffectIds: string[];
+    provenance: RecordProvenance;
+    freshness: RecordFreshness;
+};
+export type SideEffectRecord = {
+    schemaVersion: 1;
+    tenantId: string;
+    sideEffectId: string;
+    resourceId: string;
+    kind: SideEffectKind;
+    severity: ImpactSeverity;
+    provenance: RecordProvenance;
+    freshness: RecordFreshness;
+};
+export type CredentialRecord = {
+    schemaVersion: 1;
+    kind: "ghostapi.inventory-credential";
+    tenantId: string;
+    credentialId: string;
+    name: string;
+    providerId: string;
+    ownerId: string | null;
+    environmentIds: string[];
+    grantScopes: string[];
+    toolIds: string[];
+    status: "active" | "revoked";
+    issuedAt: string;
+    lastUsedAt: string | null;
+    rotatedAt?: string;
+    gatewayBound: boolean;
+    provenance: RecordProvenance;
+    freshness: RecordFreshness;
+};
+export type PolicyRecord = {
+    schemaVersion: 1;
+    kind: "ghostapi.inventory-policy";
+    tenantId: string;
+    policyId: string;
+    name: string;
+    version: string;
+    hash: string;
+    environmentIds: string[];
+    provenance: RecordProvenance;
+    freshness: RecordFreshness;
+};
+export type GraphEdge = {
+    tenantId: string;
+    edgeId: string;
+    sourceKind: NodeKind;
+    sourceId: string;
+    targetKind: NodeKind;
+    targetId: string;
+    relation: EdgeRelation;
+    provenance: RecordProvenance;
+    firstSeenAt: string;
+    lastSeenAt: string;
+};
+export type FindingRecord = {
+    schemaVersion: 1;
+    tenantId: string;
+    findingId: string;
+    kind: FindingKind;
+    severity: FindingSeverity;
+    targetKind: NodeKind | "environment" | "policy";
+    targetId: string;
+    ruleId: string;
+    reason: string;
+    basis: FindingBasis;
+    discoveredAt: string;
+    status: "open" | "resolved";
+    resolvedAt?: string;
+    remediationId?: string;
+};
+export type RemediationRecord = {
+    schemaVersion: 1;
+    tenantId: string;
+    remediationId: string;
+    findingId: string;
+    kind: RemediationKind;
+    targetKind: NodeKind | "environment" | "policy";
+    targetId: string;
+    rationale: string;
+    proposedBy: string;
+    createdAt: string;
+    status: RemediationStatus;
+    appliedAt?: string;
+    result?: {
+        description: string;
+        reducedScopes?: string[];
+        evalScenarioId?: string;
+        ownerId?: string;
+    };
+};
+export type ImportSourceRecord = {
+    tenantId: string;
+    sourceId: string;
+    sourceType: ImportSourceType;
+    sourceName: string;
+    sourceVersion?: string;
+    firstSeenAt: string;
+    lastSeenAt: string;
+    lastDigest: string;
+};
+export type ExpectedPolicyHash = {
+    environmentId: string;
+    policyHash: string;
+};
+export type ImportCounters = {
+    preventedEgressAttempts?: number;
+    reviewTimeMinutes?: number;
+    meanTimeToContainMinutes?: number;
+};
+export type ImportRunRecord = {
+    schemaVersion: 1;
+    kind: "ghostapi.inventory-import-run";
+    tenantId: string;
+    runId: string;
+    importedAt: string;
+    importedBy: string;
+    source: {
+        sourceId: string;
+        sourceType: ImportSourceType;
+        sourceName: string;
+        sourceVersion?: string;
+    };
+    digest: string;
+    expectedPolicyHashes: ExpectedPolicyHash[];
+    counters?: ImportCounters;
+    recordCounts: {
+        agents: number;
+        tools: number;
+        identities: number;
+        providers: number;
+        resources: number;
+        sideEffects: number;
+        credentials: number;
+        policies: number;
+    };
+    edgesCreated: number;
+    edgesRefreshed: number;
+    status: "completed";
+};
+export type InventoryStoreState = {
+    schemaVersion: 1;
+    kind: "ghostapi.inventory";
+    sources: ImportSourceRecord[];
+    importRuns: ImportRunRecord[];
+    agents: AgentRecord[];
+    tools: ToolRecord[];
+    identities: IdentityRecord[];
+    providers: ProviderRecord[];
+    resources: ResourceRecord[];
+    sideEffects: SideEffectRecord[];
+    credentials: CredentialRecord[];
+    policies: PolicyRecord[];
+    edges: GraphEdge[];
+    findings: FindingRecord[];
+    remediations: RemediationRecord[];
+};
+export type ImportedAgent = {
+    agentId: string;
+    name: string;
+    ownerId?: string;
+    businessPurpose?: string;
+    model?: string;
+    runtime?: string;
+    version?: string;
+    identityIds: string[];
+    environmentIds: string[];
+    gatewayManaged: boolean;
+    killSwitchEnabled: boolean;
+    lastEvidenceAt?: string;
+};
+export type ImportedTool = {
+    toolId: string;
+    name: string;
+    kind: ToolKind;
+    providerId?: string;
+    requiredScopes: string[];
+    credentialIds: string[];
+};
+export type ImportedIdentity = {
+    identityId: string;
+    principalId: string;
+    role: IdentityRole;
+    agentId?: string;
+    toolIds: string[];
+    environmentIds: string[];
+    scopes: string[];
+};
+export type ImportedProvider = {
+    providerId: string;
+    name: string;
+    providerType: string;
+    ownerId?: string;
+    environmentIds: string[];
+    resourceIds: string[];
+    gatewayBound: boolean;
+    killSwitchApplied: boolean;
+};
+export type ImportedResource = {
+    resourceId: string;
+    providerId: string;
+    resourceType: string;
+    name: string;
+    environmentIds: string[];
+    sensitive: boolean;
+    ownerId?: string;
+    businessPurpose?: string;
+    sideEffectIds: string[];
+};
+export type ImportedSideEffect = {
+    sideEffectId: string;
+    resourceId: string;
+    kind: SideEffectKind;
+    severity: ImpactSeverity;
+};
+export type ImportedCredential = {
+    credentialId: string;
+    name: string;
+    providerId: string;
+    ownerId?: string;
+    environmentIds: string[];
+    grantScopes: string[];
+    toolIds: string[];
+    status: "active" | "revoked";
+    issuedAt: string;
+    lastUsedAt?: string;
+    rotatedAt?: string;
+    gatewayBound: boolean;
+};
+export type ImportedPolicy = {
+    policyId: string;
+    name: string;
+    version: string;
+    hash: string;
+    environmentIds: string[];
+};
+export type InventoryImportPayload = {
+    schemaVersion: 1;
+    kind: "ghostapi.inventory-import";
+    source: {
+        sourceId: string;
+        sourceType: ImportSourceType;
+        sourceName: string;
+        sourceVersion?: string;
+    };
+    expectedPolicyHashes?: ExpectedPolicyHash[];
+    counters?: ImportCounters;
+    agents?: ImportedAgent[];
+    tools?: ImportedTool[];
+    identities?: ImportedIdentity[];
+    providers?: ImportedProvider[];
+    resources?: ImportedResource[];
+    sideEffects?: ImportedSideEffect[];
+    credentials?: ImportedCredential[];
+    policies?: ImportedPolicy[];
+};
+export type GraphEdgeView = GraphEdge & {
+    freshnessStatus: FreshnessStatus;
+};
+export type AttackPathStep = {
+    kind: NodeKind;
+    id: string;
+    display: string;
+};
+export type AttackPath = {
+    steps: AttackPathStep[];
+    complete: boolean;
+    edges: GraphEdge[];
+};
+export type AttackPathResult = {
+    agentId: string;
+    paths: AttackPath[];
+    incompletePaths: number;
+};
+export type BlastRadiusRule = {
+    ruleId: string;
+    explanation: string;
+};
+export type BlastRadiusResource = {
+    resourceId: string;
+    resourceType: string;
+    sensitive: boolean;
+    providerId: string;
+    sideEffects: {
+        sideEffectId: string;
+        kind: SideEffectKind;
+        severity: ImpactSeverity;
+        heuristic: boolean;
+    }[];
+    pathCount: number;
+    rules: string[];
+};
+export type BlastRadiusReport = {
+    schemaVersion: 1;
+    kind: "ghostapi.inventory-blast-radius";
+    tenantId: string;
+    agentId: string;
+    analyzedAt: string;
+    paths: AttackPath[];
+    incompletePaths: number;
+    resources: BlastRadiusResource[];
+    rules: BlastRadiusRule[];
+    heuristicNote: string;
+};
+export type CoverageMetrics = {
+    activeAgents: number;
+    policyCoveredAgents: number;
+    evidenceFreshAgents: number;
+    gatewayManagedAgents: number;
+    productionProviders: number;
+    killSwitchProviders: number;
+    directCredentials: number;
+    outsideGatewayAgents: number;
+    unownedProduction: number;
+    policyCoverageBps: number;
+    evidenceCoverageBps: number;
+    gatewayCoverageBps: number;
+    killSwitchCoverageBps: number;
+};
+export type RemovalAnalysis = {
+    schemaVersion: 1;
+    kind: "ghostapi.inventory-removal-analysis";
+    tenantId: string;
+    generatedAt: string;
+    basis: "local_inventory_data";
+    coverage: CoverageMetrics;
+    lostWithoutGhostApi: string[];
+};
+export type RoiCounterRow = {
+    sourceId: string;
+    sourceType: ImportSourceType;
+    sourceName: string;
+    value: number;
+};
+export type RoiReport = {
+    schemaVersion: 1;
+    kind: "ghostapi.inventory-roi";
+    tenantId: string;
+    generatedAt: string;
+    basis: "local_inventory_data_only";
+    activeAgentCount: number;
+    productionProviderCount: number;
+    incidents: {
+        preventedEgressAttempts: number;
+        preventedEgressSources: RoiCounterRow[];
+        reviewTimeMinutes: number | null;
+        reviewTimeSources: RoiCounterRow[];
+        meanTimeToContainMinutes: number | null;
+        meanTimeToContainSources: RoiCounterRow[];
+    };
+    remediationOutcomes: {
+        unusedGrantsRemoved: number;
+        excessiveScopeReductions: number;
+        ownedGrants: number;
+        onboardedAgents: number;
+        evalsCreated: number;
+    };
+    coverage: Pick<CoverageMetrics, "policyCoverageBps" | "evidenceCoverageBps" | "gatewayCoverageBps" | "killSwitchCoverageBps">;
+    notMeasured: string[];
+};
+export type InventorySnapshot = {
+    schemaVersion: 1;
+    kind: "ghostapi.inventory-snapshot";
+    tenantId: string;
+    agents: AgentRecord[];
+    tools: ToolRecord[];
+    identities: IdentityRecord[];
+    providers: ProviderRecord[];
+    resources: ResourceRecord[];
+    sideEffects: SideEffectRecord[];
+    credentials: CredentialRecord[];
+    policies: PolicyRecord[];
+    edges: GraphEdgeView[];
+    findings: FindingRecord[];
+    remediations: RemediationRecord[];
+    sources: ImportSourceRecord[];
+    importRuns: ImportRunRecord[];
+};
+export type InventoryExport = {
+    schemaVersion: 1;
+    kind: "ghostapi.inventory-export";
+    tenantId: string;
+    exportedAt: string;
+    inventory: Omit<InventorySnapshot, "schemaVersion" | "kind" | "edges"> & {
+        edges: GraphEdgeView[];
+    };
+    policyRecords: PolicyRecord[];
+    scenarioRefs: {
+        evalScenarioId: string;
+        forFindingId: string;
+        createdBy: string;
+    }[];
+    evidenceMetadata: {
+        agentId: string;
+        lastEvidenceAt: string | null;
+        status: FreshnessStatus;
+    }[];
+    removalAnalysis: RemovalAnalysis;
+    roi: RoiReport;
+};
+export type ImportSummary = {
+    runId: string;
+    importedAt: string;
+    digest: string;
+    recordCounts: ImportRunRecord["recordCounts"];
+    edgesCreated: number;
+    edgesRefreshed: number;
+};
+export declare class InventoryError extends Error {
+    constructor(message: string);
+}
+export declare function emptyInventoryState(): InventoryStoreState;
+export declare function sha256Digest(value: string): string;
+export declare function canonicalPayloadDigest(payload: InventoryImportPayload): string;
+export declare function sortedKeysReplacer(_key: string, value: unknown): unknown;
+export declare function validateImportPayload(value: unknown): InventoryImportPayload;
+export declare function validateState(value: unknown): InventoryStoreState;
+export declare function clone<T>(value: T): T;
+export declare function validateOperator(value: unknown): InventoryOperator;
+export declare function validateFindingsAndRemediations(value: unknown): {
+    findings: FindingRecord[];
+    remediations: RemediationRecord[];
+};
+export declare function buildRecordProvenance(source: InventoryImportPayload["source"], importedAt: string, importedBy: string): RecordProvenance;
+export declare function buildRecordFreshness(now: string): RecordFreshness;
+export declare function edgeIdFor(sourceKind: NodeKind, sourceId: string, targetKind: NodeKind, targetId: string, relation: EdgeRelation): string;
+export declare function freshnessStatusFor(lastSeenAt: string, now: string, staleDays: number): FreshnessStatus;
+export declare function daysSince(thenIso: string, nowIso: string): number;