@aiwg/cli 2026.9.4 → 2026.9.5

package/dist/src/network-analysis/citations.js

@@ -0,0 +1,107 @@
+/** Cross-reference checks after schema validation; file-byte integrity is the reader's responsibility. */
+export function validateEvidenceReferences(bundle) {
+    const sourceDigest = `sha256:${digest(bundle.capture.hashes.source.value)}`;
+    if (bundle.capture.capture_digest !== sourceDigest)
+        throw new Error('Capture identity and source hash disagree');
+    const artifacts = new Map();
+    for (const artifact of bundle.artifacts) {
+        if (artifacts.has(artifact.artifact_id))
+            throw new Error('Duplicate artifact identity');
+        artifacts.set(artifact.artifact_id, digest(artifact.digest.value));
+    }
+    const derived = new Set();
+    for (const reference of bundle.capture.hashes.derived ?? []) {
+        if (derived.has(reference.artifact_id))
+            throw new Error('Duplicate derived artifact reference');
+        derived.add(reference.artifact_id);
+        if (artifacts.get(reference.artifact_id) !== digest(reference.digest.value))
+            throw new Error('Derived artifact identity or digest disagrees');
+    }
+    const contexts = new Set(bundle.capture.analysis_contexts.map(context => context.context_digest));
+    if (contexts.size !== bundle.capture.analysis_contexts.length)
+        throw new Error('Duplicate analysis context identity');
+    const evidenceIds = new Set(bundle.evidence_items.map(item => item.evidence_id));
+    if (evidenceIds.size !== bundle.evidence_items.length)
+        throw new Error('Duplicate evidence identity');
+    for (const item of bundle.evidence_items) {
+        for (const input of item.inference?.inputs ?? []) {
+            if (input === item.evidence_id || !evidenceIds.has(input))
+                throw new Error('Inference references missing or self evidence');
+        }
+    }
+    for (const item of [...bundle.evidence_items, ...bundle.handoffs]) {
+        for (const citation of item.citations) {
+            formatEvidenceCitation(citation);
+            if (citation.capture_digest !== sourceDigest)
+                throw new Error('Citation references a different capture');
+            if (citation.locator.type === 'stream' && !contexts.has(citation.locator.context_digest)) {
+                throw new Error('Citation references an unknown analysis context');
+            }
+        }
+    }
+}
+const SHA256 = /^[a-f0-9]{64}$/;
+function digest(value) {
+    if (typeof value !== 'string' || value.length !== 64 || !SHA256.test(value))
+        throw new Error('Citation requires a lowercase SHA-256 digest');
+    return value;
+}
+function integer(value, minimum) {
+    if (!Number.isSafeInteger(value) || value < minimum)
+        throw new Error('Invalid packet citation locator');
+    return value;
+}
+/** Convert the versioned evidence schema's locator into its portable citation. */
+export function formatEvidenceCitation(citation) {
+    const hash = (value) => {
+        if (!value.startsWith('sha256:'))
+            throw new Error('Evidence citation requires SHA-256 identity');
+        return digest(value.slice(7));
+    };
+    const captureSha256 = hash(citation.capture_digest);
+    const locator = citation.locator;
+    if (locator.type === 'frame') {
+        return formatPacketCitation({ captureSha256, kind: 'frame', frameNumber: locator.frame_number });
+    }
+    if (locator.type !== 'stream')
+        throw new Error('Unsupported evidence locator');
+    return formatPacketCitation({ captureSha256, kind: 'stream', protocol: locator.protocol, streamId: locator.stream_id, contextSha256: hash(locator.context_digest) });
+}
+export function formatPacketCitation(citation) {
+    const base = `pcap:sha256:${digest(citation.captureSha256)}`;
+    if (citation.kind === 'frame')
+        return `${base}#frame=${integer(citation.frameNumber, 1)}`;
+    if (citation.kind !== 'stream' || !['tcp', 'udp'].includes(citation.protocol))
+        throw new Error('Unsupported packet citation kind');
+    return `${base}#stream=${citation.protocol}:${integer(citation.streamId, 0)}&context=${digest(citation.contextSha256)}`;
+}
+export function parsePacketCitation(value) {
+    if (typeof value !== 'string' || /\s/.test(value))
+        throw new Error('Invalid whitespace in packet citation');
+    const frame = /^pcap:sha256:([a-f0-9]{64})#frame=([1-9][0-9]*)$/.exec(value);
+    if (frame)
+        return { captureSha256: frame[1], kind: 'frame', frameNumber: integer(Number(frame[2]), 1) };
+    const stream = /^pcap:sha256:([a-f0-9]{64})#stream=(tcp|udp):(0|[1-9][0-9]*)&context=([a-f0-9]{64})$/.exec(value);
+    if (stream)
+        return { captureSha256: stream[1], kind: 'stream', protocol: stream[2], streamId: integer(Number(stream[3]), 0), contextSha256: stream[4] };
+    throw new Error('Invalid packet citation; use capture digest and frame or context-bound stream identity');
+}
+/** Verify identity before selecting a locator; a citation is never a filesystem path. */
+export function resolvePacketCitation(value, capture) {
+    const citation = parsePacketCitation(value);
+    if (citation.captureSha256 !== digest(capture.sha256))
+        throw new Error('Capture digest does not match citation');
+    if (citation.kind === 'frame') {
+        if (citation.frameNumber > integer(capture.frameCount, 0))
+            throw new Error('Cited frame is absent from capture');
+    }
+    else {
+        if (citation.contextSha256 !== capture.contextSha256)
+            throw new Error('Stream analysis context does not match citation');
+        if (!capture.streams?.some(stream => stream.protocol === citation.protocol && stream.id === citation.streamId)) {
+            throw new Error('Cited stream is absent from analysis');
+        }
+    }
+    return citation;
+}
+//# sourceMappingURL=citations.js.map

package/dist/src/network-analysis/forensics.js

@@ -0,0 +1,132 @@
+import { formatEvidenceCitation, validateEvidenceReferences } from './citations.js';
+import { assertLocalOutputAllowed } from './governance.js';
+export const FORENSIC_PACKET_EVIDENCE_SCHEMA = 'aiwg.forensics.packet-evidence.v1';
+export const ATTACK_NETWORK_TECHNIQUES = Object.freeze({
+    'T1071.001': { name: 'Application Layer Protocol: Web Protocols', url: 'https://attack.mitre.org/techniques/T1071/001/' },
+    'T1071.004': { name: 'Application Layer Protocol: DNS', url: 'https://attack.mitre.org/techniques/T1071/004/' },
+    T1573: { name: 'Encrypted Channel', url: 'https://attack.mitre.org/techniques/T1573/' },
+});
+export function createForensicPacketEvidenceEntry(input) {
+    validateEvidenceReferences(input.evidence);
+    const captureDigest = requiredString(input.evidence.capture.capture_digest, 'Capture digest');
+    if (input.verifiedCaptureDigest !== captureDigest)
+        throw new Error('Forensic handoff capture digest was not independently verified');
+    for (const [label, value] of Object.entries(input).filter(([key]) => key !== 'evidence' && key !== 'verifiedCaptureDigest')) {
+        requiredString(value, `Forensic ${label}`);
+    }
+    if (!/^E-[0-9]{3,}$/.test(input.evidenceId))
+        throw new Error('Forensic packet evidence requires an E-NNN evidence ID');
+    const sourceHash = requiredString(input.evidence.capture.hashes?.source?.value, 'Capture source hash');
+    const locatorMap = new Map();
+    for (const item of input.evidence.evidence_items) {
+        for (const citation of item.citations)
+            locatorMap.set(formatEvidenceCitation(citation), citation);
+    }
+    return {
+        schema: FORENSIC_PACKET_EVIDENCE_SCHEMA,
+        evidenceId: input.evidenceId,
+        evidenceType: 'packet-evidence-bundle',
+        caseId: input.caseId,
+        bundleId: input.evidence.bundle_id,
+        bundleStatus: input.evidence.status,
+        captureDigest,
+        sourceHash: { algorithm: 'sha256', value: sourceHash },
+        analysisContexts: (input.evidence.capture.analysis_contexts ?? []).map(context => ({
+            contextDigest: requiredString(context.context_digest, 'Analysis context digest'),
+            tool: {
+                name: requiredString(context.tool?.name, 'Analysis tool name'),
+                version: requiredString(context.tool?.version, 'Analysis tool version'),
+                executablePath: requiredString(context.tool?.executable_path, 'Analysis tool path'),
+            },
+            commandArgv: stringArray(context.command_argv, 'Analysis command argv'),
+            displayFilterDigest: requiredString(context.display_filter_digest, 'Display-filter digest'),
+            captureFilterDigest: requiredString(context.capture_filter_digest, 'Capture-filter digest'),
+            configDigests: stringArray(context.config_digests, 'Analysis config digests'),
+        })),
+        artifacts: input.evidence.artifacts.map((artifact) => ({
+            artifactId: requiredString(artifact.artifact_id, 'Artifact ID'),
+            mediaType: requiredString(artifact.media_type, 'Artifact media type'),
+            uri: requiredString(artifact.uri, 'Artifact URI'),
+            digest: `${requiredString(artifact.digest?.algorithm, 'Artifact digest algorithm')}:${requiredString(artifact.digest?.value, 'Artifact digest')}`,
+        })),
+        locators: [...locatorMap.entries()].map(([citation, value]) => ({ citation, locator: structuredClone(value.locator) })),
+        custody: {
+            receivedAt: input.receivedAt,
+            receivedFrom: input.receivedFrom,
+            receivedBy: input.receivedBy,
+            storageLocation: input.storageLocation,
+            authorizationRef: input.authorizationRef,
+            method: 'validated-bundle-handoff',
+            integrity: 'sha256-verified',
+        },
+        handling: { payload: 'withheld', disclosure: 'withheld', sensitivity: 'restricted' },
+    };
+}
+export function appendPacketEvidenceToForensicManifest(manifest, entry) {
+    const existing = manifest.evidenceItems ?? [];
+    if (existing.some((item) => item?.evidenceId === entry.evidenceId))
+        throw new Error(`Duplicate forensic evidence ID ${entry.evidenceId}`);
+    return { ...structuredClone(manifest), evidenceItems: [...structuredClone(existing), structuredClone(entry)] };
+}
+export function createForensicNetworkFinding(evidence, input) {
+    if (!/^F-[0-9]{3,}$/.test(input.findingId))
+        throw new Error('Forensic finding requires an F-NNN identifier');
+    requiredString(input.statement, 'Finding statement');
+    requiredString(input.analyst, 'Finding analyst');
+    requiredString(input.recordedAt, 'Finding timestamp');
+    stringArray(input.falsePositiveNotes, 'False-positive notes');
+    if (input.falsePositiveNotes.length === 0)
+        throw new Error('Forensic finding requires false-positive notes');
+    const available = new Map(evidence.locators.map(locator => [locator.citation, locator]));
+    const citations = input.citations.map(citation => {
+        const formatted = formatEvidenceCitation(citation);
+        if (citation.capture_digest !== evidence.captureDigest || !available.has(formatted)) {
+            throw new Error('Forensic finding citation is absent from the evidence manifest');
+        }
+        return structuredClone(available.get(formatted));
+    });
+    if (citations.length === 0)
+        throw new Error('Forensic finding requires at least one stable packet citation');
+    const attack = (input.attackTechniques ?? []).map(techniqueId => {
+        const technique = ATTACK_NETWORK_TECHNIQUES[techniqueId];
+        if (!technique)
+            throw new Error(`Unsupported ATT&CK network technique ${techniqueId}`);
+        return { techniqueId, ...technique };
+    });
+    const contentSensitivity = input.contentSensitivity ?? 'metadata';
+    if (contentSensitivity === 'payload-sensitive') {
+        if (!input.payloadAuthorization?.approvalRef.trim())
+            throw new Error('Payload-sensitive finding requires an explicit approval reference');
+        assertLocalOutputAllowed(input.payloadAuthorization.policy, { content: ['metadata', 'payload'], payloadOptIn: input.payloadAuthorization.payloadOptIn });
+    }
+    return {
+        findingId: input.findingId,
+        caseId: evidence.caseId,
+        evidenceId: evidence.evidenceId,
+        category: input.category,
+        severity: input.severity,
+        confidence: input.confidence,
+        kind: input.kind,
+        statement: input.statement,
+        analyst: input.analyst,
+        recordedAt: input.recordedAt,
+        falsePositiveNotes: [...input.falsePositiveNotes],
+        attack,
+        citations,
+        provenance: { captureDigest: evidence.captureDigest, contexts: structuredClone(evidence.analysisContexts) },
+        contentSensitivity,
+        ...(input.payloadAuthorization ? { payloadApprovalRef: input.payloadAuthorization.approvalRef } : {}),
+    };
+}
+function requiredString(value, label) {
+    if (typeof value !== 'string' || !value.trim() || value.includes('\0'))
+        throw new Error(`${label} is required`);
+    return value;
+}
+function stringArray(value, label) {
+    if (!Array.isArray(value) || value.some(item => typeof item !== 'string' || !item.trim() || item.includes('\0'))) {
+        throw new Error(`${label} must contain non-empty strings`);
+    }
+    return [...value];
+}
+//# sourceMappingURL=forensics.js.map

package/dist/src/network-analysis/governance.js

@@ -0,0 +1,216 @@
+import { createHash } from 'node:crypto';
+import { constants, lstat, open, realpath } from 'node:fs/promises';
+import path from 'node:path';
+export const NETWORK_ANALYSIS_GOVERNANCE_SCHEMA = '1.0.0';
+export const DEFAULT_NETWORK_ANALYSIS_POLICY = Object.freeze({
+    acquisition: 'offline-only',
+    output: 'metadata-only',
+    payloadAccess: 'deny',
+    providerTransfer: 'deny',
+});
+const SHA256 = /^sha256:[a-f0-9]{64}$/;
+export function assertLiveCaptureAuthorized(policy, authorization, request, now = new Date()) {
+    if (policy.acquisition !== 'live-capture-explicit-authorization')
+        fail('Live capture is disabled by policy');
+    if (authorization.state !== 'authorized')
+        fail('Live capture authorization is not active');
+    if (!authorization.authorizationId || !authorization.authority.principal || !authorization.authority.basis || !authorization.authority.approvedBy) {
+        fail('Live capture requires a complete authority record');
+    }
+    assertActiveWindow(authorization.issuedAt, authorization.expiresAt, now, 'Live capture authorization');
+    assertCaptureScope(authorization);
+    assertCaptureScope(request);
+    if (request.interface !== authorization.interface)
+        fail('Capture interface exceeds authorization');
+    if (request.captureFilter.expression !== authorization.captureFilter.expression)
+        fail('Capture filter exceeds authorization');
+    if (request.destination.path !== authorization.destination.path || request.destination.overwrite !== false)
+        fail('Capture destination exceeds authorization');
+    if (request.retention.class !== authorization.retention.class || request.retention.deleteAt !== authorization.retention.deleteAt) {
+        fail('Capture retention differs from authorization');
+    }
+    if (timestamp(authorization.retention.deleteAt, 'Retention deletion time') <= now.getTime())
+        fail('Capture retention has already expired');
+    if (request.limits.durationSeconds > authorization.limits.durationSeconds
+        || request.limits.byteLimit > authorization.limits.byteLimit
+        || request.limits.fileCount > authorization.limits.fileCount) {
+        fail('Capture limits exceed authorization');
+    }
+}
+export function assertLocalOutputAllowed(policy, request) {
+    const content = unique(request.content, 'Output content');
+    assertKnownContent(content);
+    if (!content.includes('metadata'))
+        fail('Output must be metadata-first');
+    if (content.includes('headers') && policy.output !== 'metadata-and-headers')
+        fail('Header output requires explicit policy');
+    const containsPayload = content.includes('payload') || content.includes('raw-packets');
+    if (containsPayload && (policy.payloadAccess !== 'explicit-opt-in' || request.payloadOptIn !== true)) {
+        fail('Payload and raw-packet output require explicit policy and request opt-in');
+    }
+}
+export function assertProviderTransferAllowed(policy, decision, request, now = new Date()) {
+    if (policy.providerTransfer !== 'explicit-decision')
+        fail('Provider transfer is disabled by policy');
+    if (decision.state !== 'allow')
+        fail('Provider disclosure decision does not allow transfer');
+    if (!decision.decisionId || !decision.decidedBy || !decision.provider || !decision.purpose)
+        fail('Provider disclosure decision is incomplete');
+    assertActiveWindow(decision.issuedAt, decision.expiresAt, now, 'Provider disclosure decision');
+    if (!SHA256.test(request.captureDigest) || request.captureDigest !== decision.captureDigest)
+        fail('Provider decision does not match capture identity');
+    if (request.provider !== decision.provider || request.purpose !== decision.purpose)
+        fail('Provider or purpose exceeds disclosure decision');
+    const content = unique(request.content, 'Provider content');
+    const fields = unique(request.fields, 'Provider fields');
+    assertKnownContent(content);
+    unique(decision.allowedContent, 'Allowed provider content');
+    unique(decision.allowedFields, 'Allowed provider fields');
+    if (content.length === 0 || fields.length === 0)
+        fail('Provider content and fields must be declared');
+    if (content.some(item => !decision.allowedContent.includes(item)))
+        fail('Provider content exceeds disclosure decision');
+    if (fields.some(item => !decision.allowedFields.includes(item)))
+        fail('Provider fields exceed disclosure decision');
+    if ((content.includes('payload') || content.includes('raw-packets')) && decision.payloadExplicitlyAuthorized !== true) {
+        fail('Provider payload transfer requires explicit payload authorization');
+    }
+}
+/** Produce an execFile/spawn-compatible invocation. Filters remain individual argv entries. */
+export function safeProcessSpec(file, args) {
+    if (!path.isAbsolute(file) || file.includes('\0'))
+        fail('Executable path must be absolute and contain no NUL byte');
+    const safeArgs = args.map(argument => {
+        if (typeof argument !== 'string' || argument.includes('\0'))
+            fail('Process arguments must be strings without NUL bytes');
+        return argument;
+    });
+    return Object.freeze({ file, args: Object.freeze(safeArgs), shell: false });
+}
+export function tsharkFilterArgs(filters) {
+    const args = [];
+    if (filters.captureFilter) {
+        assertText(filters.captureFilter.expression, 'Capture filter', 8192);
+        args.push('-f', filters.captureFilter.expression);
+    }
+    if (filters.displayFilter) {
+        assertText(filters.displayFilter.expression, 'Display filter', 8192);
+        args.push('-Y', filters.displayFilter.expression);
+    }
+    return args;
+}
+export async function resolveCaptureDestination(allowedRoot, destination) {
+    if (!path.isAbsolute(allowedRoot) || !path.isAbsolute(destination))
+        fail('Capture root and destination must be absolute');
+    const root = await realpath(allowedRoot);
+    const resolved = path.resolve(destination);
+    const parent = await realpath(path.dirname(resolved));
+    const relative = path.relative(root, parent);
+    if (relative.startsWith(`..${path.sep}`) || relative === '..' || path.isAbsolute(relative)) {
+        fail('Capture destination must be a file below the allowed root');
+    }
+    try {
+        await lstat(resolved);
+        fail('Capture destination already exists');
+    }
+    catch (error) {
+        if (error?.code !== 'ENOENT')
+            throw error;
+    }
+    return path.join(parent, path.basename(resolved));
+}
+/** Hashes one regular, non-symlink file without changing it and rejects concurrent mutation. */
+export async function hashEvidenceFile(file, role) {
+    const link = await lstat(file);
+    if (link.isSymbolicLink() || !link.isFile())
+        fail('Evidence path must be a regular non-symlink file');
+    const noFollow = typeof constants.O_NOFOLLOW === 'number' ? constants.O_NOFOLLOW : 0;
+    const handle = await open(file, constants.O_RDONLY | noFollow);
+    try {
+        const before = await handle.stat({ bigint: true });
+        if (!before.isFile())
+            fail('Evidence descriptor must reference a regular file');
+        if (before.dev !== BigInt(link.dev) || before.ino !== BigInt(link.ino))
+            fail('Evidence path changed before hashing');
+        if (before.size > BigInt(Number.MAX_SAFE_INTEGER))
+            fail('Evidence file is too large to represent safely');
+        const hash = createHash('sha256');
+        const buffer = Buffer.allocUnsafe(64 * 1024);
+        let position = 0;
+        while (position < before.size) {
+            const remaining = before.size - BigInt(position);
+            const length = Number(remaining < BigInt(buffer.length) ? remaining : BigInt(buffer.length));
+            const { bytesRead } = await handle.read(buffer, 0, length, position);
+            if (bytesRead === 0)
+                break;
+            hash.update(buffer.subarray(0, bytesRead));
+            position += bytesRead;
+        }
+        const after = await handle.stat({ bigint: true });
+        const linkAfter = await lstat(file);
+        if (position !== Number(before.size) || before.dev !== after.dev || before.ino !== after.ino
+            || before.size !== after.size || before.mtimeNs !== after.mtimeNs || linkAfter.isSymbolicLink()
+            || before.dev !== BigInt(linkAfter.dev) || before.ino !== BigInt(linkAfter.ino)) {
+            fail('Evidence file changed while it was being hashed');
+        }
+        return { role, algorithm: 'sha256', value: hash.digest('hex'), byteLength: Number(before.size) };
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function verifyEvidenceFile(file, expected) {
+    const actual = await hashEvidenceFile(file, expected.role);
+    if (actual.algorithm !== expected.algorithm || actual.value !== expected.value || actual.byteLength !== expected.byteLength) {
+        fail('Evidence file no longer matches its recorded identity');
+    }
+}
+function assertCaptureScope(scope) {
+    assertText(scope.interface, 'Capture interface', 255);
+    if (scope.captureFilter.type !== 'capture_filter' || scope.captureFilter.language !== 'bpf')
+        fail('Live capture requires a typed BPF capture filter');
+    assertText(scope.captureFilter.expression, 'Capture filter', 8192);
+    positiveInteger(scope.limits.durationSeconds, 86400, 'Capture duration');
+    positiveInteger(scope.limits.byteLimit, 10 * 1024 * 1024 * 1024, 'Capture byte limit');
+    positiveInteger(scope.limits.fileCount, 100, 'Capture file count');
+    if (!path.isAbsolute(scope.destination.path) || scope.destination.overwrite !== false)
+        fail('Capture destination must be absolute and non-overwriting');
+    assertText(scope.retention.class, 'Retention class', 64);
+    if (scope.retention.disposition !== 'verified-delete')
+        fail('Capture retention requires verified deletion');
+    timestamp(scope.retention.deleteAt, 'Retention deletion time');
+}
+function assertActiveWindow(issuedAt, expiresAt, now, label) {
+    const issued = timestamp(issuedAt, `${label} issued time`);
+    const expires = timestamp(expiresAt, `${label} expiry time`);
+    if (issued > expires || now.getTime() < issued || now.getTime() >= expires)
+        fail(`${label} is not active`);
+}
+function timestamp(value, label) {
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed))
+        fail(`${label} must be an ISO-8601 timestamp`);
+    return parsed;
+}
+function positiveInteger(value, maximum, label) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > maximum)
+        fail(`${label} is outside its hard bound`);
+}
+function assertText(value, label, maximum) {
+    if (typeof value !== 'string' || value.length === 0 || value.length > maximum || value.includes('\0'))
+        fail(`${label} is invalid`);
+}
+function unique(values, label) {
+    if (new Set(values).size !== values.length)
+        fail(`${label} contains duplicates`);
+    return values;
+}
+function assertKnownContent(values) {
+    const allowed = new Set(['metadata', 'headers', 'raw-packets', 'payload']);
+    if (values.some(value => !allowed.has(value)))
+        fail('Unknown governed content class');
+}
+function fail(message) {
+    throw new Error(message);
+}
+//# sourceMappingURL=governance.js.map

package/dist/src/network-analysis/index.js

@@ -0,0 +1,10 @@
+export * from './analyzer.js';
+export * from './citations.js';
+export * from './forensics.js';
+export * from './governance.js';
+export * from './probe.js';
+export * from './recipes.js';
+export * from './research.js';
+export * from './termshark.js';
+export * from './verification.js';
+//# sourceMappingURL=index.js.map