Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/packages/storage/src/scan/index.ts
T

284 lines
7.3 KiB
TypeScript

export * from "./pre-upload-types.js";
export { createMagicBytesScanAdapter, type MagicBytesScanAdapterOptions } from "./magic-bytes-adapter.js";
export { DEFAULT_ALLOW_LIST, resolveAllowList } from "./allow-list.js";
export {
createClamAVStorageScanner,
createClamAVBufferScanner,
ClamAVUnreachableError,
isClamAVUnreachableError,
type ClamAVScannerConfig,
type ClamAVBufferScanner,
type ClamAVBufferScannerConfig,
type ClamScanClient,
type ClamScanResult,
} from "./clamav-scanner.js";
export { createS3StorageQuarantineAdapter, type S3QuarantineConfig } from "./s3-quarantine.js";
export type ScanVerdict = "clean" | "infected" | "error";
export interface StorageScanTarget {
bucket: string;
key: string;
requestId?: string;
metadata?: Record<string, unknown>;
}
export interface StorageScannerInput {
bucket: string;
key: string;
}
export type StorageScannerResult =
| {
verdict: "clean";
engine?: string;
}
| {
verdict: "infected";
signature: string;
engine?: string;
quarantineKey?: string;
};
export interface StorageScanner {
scanObject(target: StorageScannerInput): Promise<StorageScannerResult> | StorageScannerResult;
}
export interface StorageQuarantineInput {
bucket: string;
key: string;
quarantineKey?: string;
signature: string;
}
export interface StorageQuarantineResult {
bucket?: string;
key?: string;
quarantineKey?: string;
action?: "copied" | "moved" | "tagged" | "skipped";
}
export interface StorageQuarantineAdapter {
quarantineObject(input: StorageQuarantineInput): Promise<StorageQuarantineResult> | StorageQuarantineResult;
}
export interface StorageScanDiagnostic {
code: StorageScanErrorCode;
message: string;
upstream?: {
name?: string;
message?: string;
status?: number;
requestId?: string;
};
}
export type StorageScanErrorCode =
| "invalid_target"
| "scanner_failed"
| "quarantine_failed";
export type StorageScanResult =
| {
verdict: "clean";
bucket: string;
key: string;
scannedAt: Date;
engine?: string;
}
| {
verdict: "infected";
bucket: string;
key: string;
scannedAt: Date;
engine?: string;
signature: string;
quarantineKey?: string;
quarantine?: StorageQuarantineResult;
}
| {
verdict: "error";
bucket?: string;
key?: string;
scannedAt: Date;
error: StorageScanDiagnostic;
};
export interface StorageScanService {
scanObject(target: StorageScanTarget): Promise<StorageScanResult>;
}
export interface CreateStorageScanServiceInput {
scanner: StorageScanner;
quarantine?: StorageQuarantineAdapter;
now?: () => Date;
}
export class StorageScanError extends Error {
readonly code: StorageScanErrorCode;
readonly details: StorageScanDiagnostic;
override readonly cause?: unknown;
constructor(
code: StorageScanErrorCode,
message: string,
details: StorageScanDiagnostic,
options: { cause?: unknown } = {},
) {
super(message);
this.name = "StorageScanError";
this.code = code;
this.details = details;
this.cause = options.cause;
}
}
export function createStorageScanService({
scanner,
quarantine,
now = () => new Date(),
}: CreateStorageScanServiceInput): StorageScanService {
return {
async scanObject(target) {
const scannedAt = now();
const normalizedTarget = normalizeTarget(target);
if (!normalizedTarget) {
return {
verdict: "error",
bucket: isPresent(target.bucket) ? target.bucket : undefined,
key: isPresent(target.key) ? target.key : undefined,
scannedAt,
error: createDiagnostic(
"invalid_target",
"Storage scan target bucket and key must be non-empty strings.",
),
};
}
let scanResult: StorageScannerResult;
try {
scanResult = await scanner.scanObject(normalizedTarget);
} catch (cause) {
return {
verdict: "error",
bucket: normalizedTarget.bucket,
key: normalizedTarget.key,
scannedAt,
error: createDiagnostic(
"scanner_failed",
"Storage scanner failed while scanning object.",
cause,
),
};
}
if (scanResult.verdict === "clean") {
return {
verdict: "clean",
bucket: normalizedTarget.bucket,
key: normalizedTarget.key,
scannedAt,
engine: scanResult.engine,
};
}
const quarantineKey = scanResult.quarantineKey;
let quarantineResult: StorageQuarantineResult | undefined;
if (quarantine) {
try {
quarantineResult = await quarantine.quarantineObject({
bucket: normalizedTarget.bucket,
key: normalizedTarget.key,
quarantineKey,
signature: scanResult.signature,
});
} catch (cause) {
return {
verdict: "error",
bucket: normalizedTarget.bucket,
key: normalizedTarget.key,
scannedAt,
error: createDiagnostic(
"quarantine_failed",
"Storage quarantine failed for infected object.",
cause,
),
};
}
}
return {
verdict: "infected",
bucket: normalizedTarget.bucket,
key: normalizedTarget.key,
scannedAt,
engine: scanResult.engine,
signature: scanResult.signature,
quarantineKey: quarantineResult?.quarantineKey ?? quarantineKey,
quarantine: quarantineResult,
};
},
};
}
function normalizeTarget(target: StorageScanTarget): StorageScannerInput | null {
if (!isPresent(target.bucket) || !isPresent(target.key)) {
return null;
}
return {
bucket: target.bucket.trim(),
key: target.key.trim(),
};
}
function createDiagnostic(
code: StorageScanErrorCode,
message: string,
cause?: unknown,
): StorageScanDiagnostic {
const upstream = extractRedactedUpstreamDetails(cause);
return {
code,
message,
...(upstream ? { upstream } : {}),
};
}
function extractRedactedUpstreamDetails(
cause: unknown,
): StorageScanDiagnostic["upstream"] {
if (!isRecord(cause)) {
return undefined;
}
const metadata = isRecord(cause.$metadata) ? cause.$metadata : undefined;
const status = typeof metadata?.httpStatusCode === "number" ? metadata.httpStatusCode : undefined;
const requestId = typeof metadata?.requestId === "string" ? metadata.requestId : undefined;
const message = typeof cause.message === "string" ? redactSecretLikeText(cause.message) : undefined;
return {
name: typeof cause.name === "string" ? cause.name : undefined,
message,
status,
requestId,
};
}
function redactSecretLikeText(message: string): string {
return message
.replace(/(access[_-]?key(?:id)?|secret[_-]?access[_-]?key|session[_-]?token|credential|authorization|token|password)(\s*[=:]\s*)\S+/gi, "$1$2[redacted]")
.replace(/(body)(\s*[=:]\s*)\S+/gi, "$1$2[redacted]");
}
function isPresent(value: unknown): value is string {
return typeof value === "string" && value.trim().length > 0;
}
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null;
}