@upx-us/shield 0.2.12-beta

package/dist/src/redactor/index.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * src/redactor/index.ts — Strategy engine, event redaction, and public API.
+ *
+ * This module wires vault + strategies into a single redaction engine.
+ * All imports of './redactor' resolve here (TypeScript: directory + index.ts).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyFieldRedaction = applyFieldRedaction;
+exports.redactEvent = redactEvent;
+exports.redactUsername = redactUsername;
+exports.redactHostname = redactHostname;
+exports.redactPath = redactPath;
+exports.redactCommand = redactCommand;
+exports.init = init;
+exports.flush = flush;
+exports.reverseLookup = reverseLookup;
+exports.getAllMappings = getAllMappings;
+exports._initForTesting = _initForTesting;
+const strategies_1 = require("./strategies");
+const vault_1 = require("./vault");
+const events_1 = require("../events");
+const base_1 = require("../events/base");
+// ─── Strategy Registry ────────────────────────────────────────────────────────
+const strategyMap = new Map(strategies_1.strategies.map(s => [s.key, s]));
+// ─── Engine ───────────────────────────────────────────────────────────────────
+/**
+ * Apply a single FieldRedaction rule to an object via dot-notation path.
+ * Missing fields and null values are silently skipped.
+ * Unknown strategy keys throw a descriptive error.
+ */
+function applyFieldRedaction(obj, rule) {
+    const strategy = strategyMap.get(rule.strategy);
+    if (!strategy)
+        throw new Error(`[redactor] Unknown redaction strategy: '${rule.strategy}'. Register it in src/redactor/strategies/index.ts`);
+    const parts = rule.path.split('.');
+    let cur = obj;
+    for (let i = 0; i < parts.length - 1; i++) {
+        if (cur == null || typeof cur !== 'object')
+            return;
+        cur = cur[parts[i]];
+    }
+    const last = parts[parts.length - 1];
+    if (cur == null || typeof cur !== 'object' || cur[last] == null)
+        return;
+    cur[last] = strategy.redact(String(cur[last]), vault_1.hmacHash);
+}
+// ─── High-Level API ───────────────────────────────────────────────────────────
+/**
+ * Deep-redact a Shield envelope. Returns a new object (does not mutate input).
+ * Applies base redactions + schema-specific redactions based on tool_category.
+ */
+function redactEvent(envelope) {
+    const e = JSON.parse(JSON.stringify(envelope));
+    // Source-level: hostname in the source block always gets redacted
+    if (e.source?.hostname) {
+        const hs = strategyMap.get('hostname');
+        if (hs)
+            e.source.hostname = hs.redact(e.source.hostname, vault_1.hmacHash);
+    }
+    if (!e.event)
+        return e;
+    // Base redactions (principal.hostname, principal.user) — always apply
+    for (const rule of base_1.baseRedactions) {
+        applyFieldRedaction(e.event, rule);
+    }
+    // Schema-specific redactions via tool_category discriminator
+    const category = e.event.tool_category;
+    if (category) {
+        const schema = events_1.schemas.find(s => s.category === category);
+        if (schema) {
+            for (const rule of schema.redactions) {
+                applyFieldRedaction(e.event, rule);
+            }
+        }
+    }
+    return e;
+}
+// ─── Individual Strategy Functions (backwards-compat + direct use) ────────────
+function redactUsername(value) {
+    const s = strategyMap.get('username');
+    return s ? s.redact(value, vault_1.hmacHash) : value;
+}
+function redactHostname(value) {
+    const s = strategyMap.get('hostname');
+    return s ? s.redact(value, vault_1.hmacHash) : value;
+}
+function redactPath(value) {
+    const s = strategyMap.get('path');
+    return s ? s.redact(value, vault_1.hmacHash) : value;
+}
+function redactCommand(value) {
+    const s = strategyMap.get('command');
+    return s ? s.redact(value, vault_1.hmacHash) : value;
+}
+// ─── Lifecycle ────────────────────────────────────────────────────────────────
+function init() { (0, vault_1.initVault)(); }
+function flush() { (0, vault_1.flushVault)(); }
+// ─── Reverse Lookup ───────────────────────────────────────────────────────────
+function reverseLookup(token) {
+    return (0, vault_1.reverseLookup)(token);
+}
+function getAllMappings() {
+    return (0, vault_1.getAllMappings)();
+}
+// ─── Testing ──────────────────────────────────────────────────────────────────
+function _initForTesting(secret) {
+    (0, vault_1._initVaultForTesting)(secret);
+}

package/dist/src/redactor/strategies/command.d.ts

@@ -0,0 +1,2 @@
+import type { RedactionStrategy } from '../base';
+export declare const commandStrategy: RedactionStrategy;

package/dist/src/redactor/strategies/command.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.commandStrategy = void 0;
+exports.commandStrategy = {
+    key: 'command',
+    description: 'Redacts usernames embedded in shell command strings: SSH user@host patterns, /Users/X/ paths, /home/X/ paths. Produces user:HASH tokens.',
+    redact(value, hmac) {
+        if (!value || value.length === 0)
+            return value;
+        let result = value;
+        // SSH user@host patterns (e.g. ssh alice@192.168.1.1, scp bob@server:/path)
+        result = result.replace(/(\b)([\w.-]+)@([\d.]+|[\w.-]+\.\w+)/g, (_, pre, user, host) => `${pre}${hmac('user', user)}@${host}`);
+        // macOS home paths
+        result = result.replace(/\/Users\/([\w.-]+)\//g, (_, user) => `/Users/${hmac('user', user)}/`);
+        // Linux home paths
+        result = result.replace(/\/home\/([\w.-]+)\//g, (_, user) => `/home/${hmac('user', user)}/`);
+        return result;
+    },
+};

package/dist/src/redactor/strategies/hostname.d.ts

@@ -0,0 +1,2 @@
+import type { RedactionStrategy } from '../base';
+export declare const hostnameStrategy: RedactionStrategy;

package/dist/src/redactor/strategies/hostname.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hostnameStrategy = void 0;
+exports.hostnameStrategy = {
+    key: 'hostname',
+    description: 'Redacts machine hostnames. IPv4 addresses are passed through unchanged — they have detection value in security rules. Produces host:HASH tokens.',
+    redact(value, hmac) {
+        if (!value || value.length === 0)
+            return value;
+        // IPv4 addresses are not redacted — they have detection value for lateral movement rules
+        if (/^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(value))
+            return value;
+        return hmac('host', value);
+    },
+};

package/dist/src/redactor/strategies/index.d.ts

@@ -0,0 +1,13 @@
+import { usernameStrategy } from './username';
+import { hostnameStrategy } from './hostname';
+import { pathStrategy } from './path';
+import { commandStrategy } from './command';
+import { secretKeyStrategy } from './secret-key';
+import type { RedactionStrategy } from '../base';
+export { usernameStrategy, hostnameStrategy, pathStrategy, commandStrategy, secretKeyStrategy };
+/**
+ * Ordered registry of all redaction strategies.
+ * The engine resolves strategies by their `key` field.
+ * Order here does not affect execution — strategies are looked up by key.
+ */
+export declare const strategies: RedactionStrategy[];

package/dist/src/redactor/strategies/index.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.strategies = exports.secretKeyStrategy = exports.commandStrategy = exports.pathStrategy = exports.hostnameStrategy = exports.usernameStrategy = void 0;
+const username_1 = require("./username");
+Object.defineProperty(exports, "usernameStrategy", { enumerable: true, get: function () { return username_1.usernameStrategy; } });
+const hostname_1 = require("./hostname");
+Object.defineProperty(exports, "hostnameStrategy", { enumerable: true, get: function () { return hostname_1.hostnameStrategy; } });
+const path_1 = require("./path");
+Object.defineProperty(exports, "pathStrategy", { enumerable: true, get: function () { return path_1.pathStrategy; } });
+const command_1 = require("./command");
+Object.defineProperty(exports, "commandStrategy", { enumerable: true, get: function () { return command_1.commandStrategy; } });
+const secret_key_1 = require("./secret-key");
+Object.defineProperty(exports, "secretKeyStrategy", { enumerable: true, get: function () { return secret_key_1.secretKeyStrategy; } });
+/**
+ * Ordered registry of all redaction strategies.
+ * The engine resolves strategies by their `key` field.
+ * Order here does not affect execution — strategies are looked up by key.
+ */
+exports.strategies = [
+    username_1.usernameStrategy,
+    hostname_1.hostnameStrategy,
+    path_1.pathStrategy,
+    command_1.commandStrategy,
+    secret_key_1.secretKeyStrategy,
+];

package/dist/src/redactor/strategies/path.d.ts

@@ -0,0 +1,2 @@
+import type { RedactionStrategy } from '../base';
+export declare const pathStrategy: RedactionStrategy;

package/dist/src/redactor/strategies/path.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pathStrategy = void 0;
+const HOME_PATTERNS = [
+    [/^(\/Users\/)([\w.-]+)(\/.*|$)/, '$1', '$3'], // macOS
+    [/^(\/home\/)([\w.-]+)(\/.*|$)/, '$1', '$3'], // Linux
+    [/^(C:\\Users\\)([\w.-]+)(\\.*|$)/i, '$1', '$3'], // Windows
+];
+exports.pathStrategy = {
+    key: 'path',
+    description: 'Redacts the username segment in home directory paths (/Users/X/, /home/X/, C:\\Users\\X\\). Preserves the rest of the path for investigation value. Produces user:HASH tokens (same category as username — both identify the same person).',
+    redact(value, hmac) {
+        if (!value || value.length === 0)
+            return value;
+        for (const [pattern] of HOME_PATTERNS) {
+            const match = value.match(pattern);
+            if (match) {
+                return `${match[1]}${hmac('user', match[2])}${match[3] ?? ''}`;
+            }
+        }
+        return value;
+    },
+};

package/dist/src/redactor/strategies/secret-key.d.ts

@@ -0,0 +1,2 @@
+import type { RedactionStrategy } from '../base';
+export declare const secretKeyStrategy: RedactionStrategy;

package/dist/src/redactor/strategies/secret-key.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.secretKeyStrategy = void 0;
+exports.secretKeyStrategy = {
+    key: 'secret-key',
+    description: 'Detects and redacts API keys, bearer tokens, and secrets in free-text fields (command strings, arguments). Produces secret:HASH tokens.',
+    redact(value, hmac) {
+        if (!value || value.length === 0)
+            return value;
+        let result = value;
+        // AWS access key IDs (e.g. AKIAIOSFODNN7EXAMPLE)
+        // Note: no capture groups — the entire match is the secret
+        result = result.replace(/(AKIA[0-9A-Z]{16})/g, (_, key) => hmac('secret', key));
+        // CLI flags with secrets: --token=sk_live_xxx, --api-key sk_live_xxx, --password=abc123
+        result = result.replace(/(--(?:token|api[_-]?key|secret|password)[=\s]+)(\S+)/gi, (_, flag, secret) => `${flag}${hmac('secret', secret)}`);
+        // Bearer tokens in Authorization headers
+        result = result.replace(/(Bearer\s+)(\S+)/gi, (_, prefix, token) => `${prefix}${hmac('secret', token)}`);
+        // ENV-style assignments: SECRET=value, API_KEY=value, TOKEN=value, PASSWORD=value
+        result = result.replace(/((?:SECRET|TOKEN|KEY|PASSWORD|API_KEY)=)(\S+)/gi, (_, prefix, secret) => `${prefix}${hmac('secret', secret)}`);
+        return result;
+    },
+};

package/dist/src/redactor/strategies/username.d.ts

@@ -0,0 +1,2 @@
+import type { RedactionStrategy } from '../base';
+export declare const usernameStrategy: RedactionStrategy;

package/dist/src/redactor/strategies/username.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.usernameStrategy = void 0;
+exports.usernameStrategy = {
+    key: 'username',
+    description: 'Redacts OS usernames. Produces user:HASH tokens.',
+    redact(value, hmac) {
+        if (!value || value.length === 0)
+            return value;
+        return hmac('user', value);
+    },
+};

package/dist/src/redactor/vault.d.ts

@@ -0,0 +1,25 @@
+/**
+ * src/redactor/vault.ts — Key management and encrypted mapping store.
+ *
+ * The vault owns all I/O. Key lifecycle, map persistence, reverse lookup —
+ * everything involving files or crypto state lives here. No other module in
+ * the redactor touches the filesystem.
+ *
+ * Security layers:
+ *   - File permissions: 0o600 on key and vault files
+ *   - Encryption at rest: AES-256-GCM with scrypt-derived key
+ *   - Atomic writes: write to .tmp then rename (prevents mid-write corruption)
+ *   - In-memory isolation: state fully encapsulated in this module
+ *   - Test isolation: _initVaultForTesting() uses deterministic secret, no file I/O
+ */
+export declare function initVault(): void;
+export declare function flushVault(): void;
+/**
+ * Produce a deterministic token for a (category, value) pair and record the
+ * reverse mapping. This is the HmacFn injected into every strategy.
+ */
+export declare function hmacHash(category: string, value: string): string;
+export declare function reverseLookup(token: string): string | null;
+export declare function getAllMappings(): Record<string, string>;
+/** For testing only — deterministic secret, zero file I/O. */
+export declare function _initVaultForTesting(secret: string): void;

package/dist/src/redactor/vault.js

@@ -0,0 +1,209 @@
+"use strict";
+/**
+ * src/redactor/vault.ts — Key management and encrypted mapping store.
+ *
+ * The vault owns all I/O. Key lifecycle, map persistence, reverse lookup —
+ * everything involving files or crypto state lives here. No other module in
+ * the redactor touches the filesystem.
+ *
+ * Security layers:
+ *   - File permissions: 0o600 on key and vault files
+ *   - Encryption at rest: AES-256-GCM with scrypt-derived key
+ *   - Atomic writes: write to .tmp then rename (prevents mid-write corruption)
+ *   - In-memory isolation: state fully encapsulated in this module
+ *   - Test isolation: _initVaultForTesting() uses deterministic secret, no file I/O
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initVault = initVault;
+exports.flushVault = flushVault;
+exports.hmacHash = hmacHash;
+exports.reverseLookup = reverseLookup;
+exports.getAllMappings = getAllMappings;
+exports._initVaultForTesting = _initVaultForTesting;
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+// ─── Paths ────────────────────────────────────────────────────────────────────
+const SHIELD_DATA_DIR = path.join(os.homedir(), '.openclaw', 'shield', 'data');
+const KEY_FILE = path.join(SHIELD_DATA_DIR, 'redaction-key.secret');
+const VAULT_FILE = path.join(SHIELD_DATA_DIR, 'redaction-vault.json');
+const VAULT_TMP = `${VAULT_FILE}.tmp`;
+// Legacy plaintext map (pre-vault) — migrated on first init
+const LEGACY_MAP = path.join(SHIELD_DATA_DIR, 'redaction-map.json');
+// ─── State ────────────────────────────────────────────────────────────────────
+let _secret = null;
+let _map = {};
+let _mapDirty = false;
+let _testMode = false;
+// ─── Crypto Helpers ───────────────────────────────────────────────────────────
+function deriveVaultKey(secret) {
+    // Fixed salt is acceptable for v1: the HMAC secret is already random (32 hex bytes),
+    // so we're protecting against at-rest reads, not dictionary attacks on the key.
+    return crypto.scryptSync(secret, 'shield-vault-salt', 32);
+}
+function encryptMap(data, key) {
+    const iv = crypto.randomBytes(16);
+    const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+    const encrypted = Buffer.concat([cipher.update(data, 'utf8'), cipher.final()]);
+    return {
+        iv: iv.toString('hex'),
+        tag: cipher.getAuthTag().toString('hex'),
+        ciphertext: encrypted.toString('hex'),
+    };
+}
+function decryptMap(env, key) {
+    const decipher = crypto.createDecipheriv('aes-256-gcm', key, Buffer.from(env.iv, 'hex'));
+    decipher.setAuthTag(Buffer.from(env.tag, 'hex'));
+    return decipher.update(env.ciphertext, 'hex', 'utf8') + decipher.final('utf8');
+}
+// ─── Key Management ───────────────────────────────────────────────────────────
+function getSecret() {
+    if (_secret)
+        return _secret;
+    if (!_testMode && fs.existsSync(KEY_FILE)) {
+        _secret = fs.readFileSync(KEY_FILE, 'utf8').trim();
+    }
+    else if (!_testMode) {
+        _secret = crypto.randomBytes(32).toString('hex');
+        fs.mkdirSync(SHIELD_DATA_DIR, { recursive: true });
+        fs.writeFileSync(KEY_FILE, _secret, { mode: 0o600 });
+        console.log(`[vault] Generated new HMAC key at ${KEY_FILE}`);
+    }
+    return _secret;
+}
+// ─── Vault I/O ────────────────────────────────────────────────────────────────
+function loadVault() {
+    if (_testMode)
+        return;
+    // Try primary vault file, fall back to .tmp if primary is missing (crash recovery)
+    let fileToLoad = null;
+    if (fs.existsSync(VAULT_FILE))
+        fileToLoad = VAULT_FILE;
+    else if (fs.existsSync(VAULT_TMP)) {
+        console.warn('[vault] Primary vault missing, recovering from .tmp file');
+        fileToLoad = VAULT_TMP;
+    }
+    if (fileToLoad) {
+        try {
+            const raw = fs.readFileSync(fileToLoad, 'utf8');
+            const envelope = JSON.parse(raw);
+            const key = deriveVaultKey(getSecret());
+            const decrypted = decryptMap(envelope, key);
+            _map = JSON.parse(decrypted);
+        }
+        catch (e) {
+            console.warn(`[vault] Could not load vault file (${e.message}) — starting fresh`);
+            _map = {};
+        }
+        return;
+    }
+    // Migrate from legacy plaintext redaction-map.json if it exists.
+    // Check both locations: the new data dir AND the old project-root config/ directory
+    // (pre-v0.2 bridge stored it at config/redaction-map.json relative to the repo root).
+    const OLD_PROJECT_MAP = path.join(__dirname, '..', '..', 'config', 'redaction-map.json');
+    const legacyPath = [LEGACY_MAP, OLD_PROJECT_MAP].find(p => fs.existsSync(p));
+    if (legacyPath) {
+        try {
+            const legacy = JSON.parse(fs.readFileSync(legacyPath, 'utf8'));
+            const count = Object.keys(legacy).length;
+            _map = legacy;
+            _mapDirty = true;
+            flushVault(); // write encrypted vault immediately
+            fs.unlinkSync(legacyPath);
+            console.log(`[vault] Migrated ${count} mappings from legacy plaintext map (${legacyPath})`);
+        }
+        catch (e) {
+            console.warn(`[vault] Legacy map migration failed: ${e.message}`);
+            _map = {};
+        }
+    }
+}
+function saveVault() {
+    if (!_mapDirty)
+        return;
+    try {
+        fs.mkdirSync(SHIELD_DATA_DIR, { recursive: true });
+        const key = deriveVaultKey(getSecret());
+        const encrypted = encryptMap(JSON.stringify(_map), key);
+        const content = JSON.stringify(encrypted);
+        // Atomic write: .tmp first, then rename
+        fs.writeFileSync(VAULT_TMP, content, { mode: 0o600 });
+        fs.renameSync(VAULT_TMP, VAULT_FILE);
+        _mapDirty = false;
+    }
+    catch (e) {
+        console.error(`[vault] Failed to persist vault: ${e.message}`);
+    }
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+function initVault() {
+    getSecret();
+    loadVault();
+    console.log(`[vault] Initialized. ${Object.keys(_map).length} existing mappings.`);
+}
+function flushVault() {
+    saveVault();
+}
+/**
+ * Produce a deterministic token for a (category, value) pair and record the
+ * reverse mapping. This is the HmacFn injected into every strategy.
+ */
+function hmacHash(category, value) {
+    const hash = crypto.createHmac('sha256', getSecret())
+        .update(`${category}:${value}`)
+        .digest('hex')
+        .substring(0, 12);
+    const token = `${category}:${hash}`;
+    if (!_map[token]) {
+        _map[token] = value;
+        _mapDirty = true;
+    }
+    return token;
+}
+function reverseLookup(token) {
+    return _map[token] ?? null;
+}
+function getAllMappings() {
+    return { ..._map };
+}
+/** For testing only — deterministic secret, zero file I/O. */
+function _initVaultForTesting(secret) {
+    _secret = secret;
+    _map = {};
+    _mapDirty = false;
+    _testMode = true;
+}

package/dist/src/sender.d.ts

@@ -0,0 +1,29 @@
+/**
+ * sender.ts — Shield ingest API sender
+ *
+ * Posts events to the Shield ingest API via HMAC-SHA256 authentication.
+ * Events are batched and sent to the configured Shield endpoint only —
+ * no cloud provider details are exposed in this module.
+ */
+import { EnvelopeEvent } from './transformer';
+import { Config, ShieldCredentials } from './config';
+export declare const REQUEST_TIMEOUT_MS = 30000;
+/** Exported for testing only — computes HMAC with an explicit secret */
+export declare function _signRequestWithSecret(secret: string, instanceId: string, nonce: string): string;
+export interface SendResult {
+    success: boolean;
+    statusCode?: number;
+    body?: string;
+    eventCount: number;
+}
+export declare function sendEvents(events: EnvelopeEvent[], config: Config): Promise<SendResult[]>;
+/**
+ * reportInstance — PUT /v1/instance
+ *
+ * Reports machine + software metadata to the Shield platform for score
+ * calculation and dashboard display. This is NOT a security event and does
+ * NOT go to Chronicle — it goes directly to the platform API via Cloud Run.
+ *
+ * Called periodically (default: every 5 minutes) by the bridge/plugin loop.
+ */
+export declare function reportInstance(payload: Record<string, unknown>, credentials: ShieldCredentials): Promise<boolean>;