quelda
Version:
PDF & Illustrator security scanner (WebAssembly): files + policy in, verdict out
162 lines (161 loc) • 6.24 kB
TypeScript
/** Preset names (`policy.schema.json` `preset`). */
export declare const PRESETS: readonly ["strict", "balanced", "permissive"];
export type Preset = (typeof PRESETS)[number];
/** Category keys (design §5.6), in engine order. */
export declare const CATEGORIES: readonly ["filetype", "postscript", "active_content", "embedded", "external", "forms", "xml", "structure", "encryption", "codecs", "resource"];
export type Category = (typeof CATEGORIES)[number];
/** What a policy can set for a category or rule. */
export declare const ACTIONS: readonly ["block", "warn", "off"];
export type Action = (typeof ACTIONS)[number];
export declare const SEVERITIES: readonly ["critical", "high", "medium", "low", "info"];
export type Severity = (typeof SEVERITIES)[number];
export declare const STAGES: readonly ["preview", "stable"];
export type Stage = (typeof STAGES)[number];
export declare const STATUSES: readonly ["PASS", "REJECT", "ERROR"];
export type Status = (typeof STATUSES)[number];
/** Rule ID, `CATEGORY.NAME` (e.g. `ACTIVE.LAUNCH`); stable forever. */
export type RuleId = string;
/** Engine guardrails; exceeding one makes the verdict `ERROR` (`LIMIT.*`). */
export interface PolicyLimits {
max_file_bytes?: number;
max_objects?: number;
/** Clamped to 512 by the engine. */
max_nesting_depth?: number;
max_decoded_bytes_total?: number;
max_decoded_bytes_per_stream?: number;
max_compression_ratio?: number;
max_revisions?: number;
}
/** Detection thresholds of some rules; exceeding one is a finding. */
export interface PolicyThresholds {
max_image_pixels?: number;
max_page_side_pt?: number;
max_pages?: number;
max_filter_chain?: number;
max_trailing_bytes?: number;
}
/**
* Scan policy (`schemas/policy.schema.json`, design §6). Every field is
* optional; `{}` is the `balanced` preset. The engine parses it strictly:
* unknown fields, `null`, wrong types, unknown categories and rule IDs the
* engine does not know give an `ERROR` verdict with `POLICY.INVALID`.
*/
export interface Policy {
preset?: Preset;
/** Category overrides; beat the preset. */
categories?: {
[C in Category]?: Action;
};
/** Rule overrides by ID; beat the category. Unknown IDs are rejected. */
rules?: {
[id: RuleId]: Action;
};
limits?: PolicyLimits;
thresholds?: PolicyThresholds;
/** Stop at the first block finding. */
stop_on_first?: boolean;
/** Allow lowering locked rules (reported in the verdict). */
unsafe_allow_unlock?: boolean;
}
/** Where a rule fired. Every field is optional. */
export interface Location {
/** `"N G"` of the object. */
object?: string;
/** Byte offset in the file (object, its object stream, or the finding). */
offset?: number;
/** `file` or `objstm:N`. */
source?: string;
/** From the object to the nested dictionary, e.g. `/AA/O`. */
path?: string;
/** Offset of a content operator in the decoded stream. */
op_offset?: number;
detail?: string;
}
/** One rule that fired (all its hits merged). */
export interface Violation {
rule_id: RuleId;
category: Category;
severity: Severity;
/** `block` in `violations`, `warn` in `warnings`. */
action: Exclude<Action, 'off'>;
message: string;
/** Every hit, including those beyond the kept locations. */
count: number;
/** At most 64. */
locations: Location[];
}
/**
* Why a verdict is `ERROR`. Engine codes start with `LIMIT.`, `ENGINE.` or
* `POLICY.`; the codes this package adds itself are {@link ScannerErrorCode}.
*/
export interface EngineError {
code: string;
message: string;
offset?: number;
}
export interface VerdictPolicy {
/** `null` when the policy could not be parsed. */
preset: Preset | null;
/** `sha256:<hex>` of the canonical policy; `null` when it could not be parsed. */
digest: string | null;
unsafe_allow_unlock: boolean;
stop_on_first: boolean;
}
export interface VerdictStats {
bytes: number;
objects: number;
revisions: number;
decoded_bytes: number;
/**
* Engine time in ms. The WASM engine has no clock, so this package fills it
* in from `performance.now()` around the engine call (in the worker).
*/
duration_ms: number;
}
/**
* Scan result (`schemas/verdict.schema.json`, design §7).
* `valid` is `true` exactly when `status` is `PASS`; treat anything else as
* invalid.
*/
export interface Verdict {
valid: boolean;
status: Status;
/** Rules that fired with action `block`, sorted by `rule_id`. */
violations: Violation[];
/** Rules that fired with action `warn`, sorted by `rule_id`. */
warnings: Violation[];
errors: EngineError[];
engine_version: string;
policy: VerdictPolicy;
stats: VerdictStats;
}
/** One entry of `listRules()` (`schemas/rules.schema.json`). */
export interface RuleInfo {
id: RuleId;
category: Category;
severity: Severity;
/** Action in the `balanced` preset. */
default_action: Action;
/** Policy cannot lower it below `block` (except `unsafe_allow_unlock`). */
locked: boolean;
stage: Stage;
/** Engine version that added the rule. */
since: string;
message: string;
description: string;
}
/**
* Error codes of `ERROR` verdicts made by this package (not by the engine):
* - `LIMIT.TIMEOUT`: the scan ran longer than `timeoutMs`; the worker was killed.
* - `ENGINE.ABORTED`: the `AbortSignal` fired or `terminate()` was called.
* - `ENGINE.WORKER`: the worker or the WASM engine failed (crash, trap, load
* error, malformed reply).
* - `ENGINE.INPUT`: the input or the scan options could not be used.
* - `POLICY.INVALID`: the policy object could not be serialized to JSON.
*/
export declare const SCANNER_ERROR_CODES: readonly ["LIMIT.TIMEOUT", "ENGINE.ABORTED", "ENGINE.WORKER", "ENGINE.INPUT", "POLICY.INVALID"];
export type ScannerErrorCode = (typeof SCANNER_ERROR_CODES)[number];
/** What `scan` accepts. `File` is a `Blob`. */
export type ScanInput = Blob | ArrayBuffer | ArrayBufferView;
/** A policy object, or policy JSON text passed to the engine verbatim. */
export type PolicyInput = Policy | string;