@token-security/clawdit 0.1.0

package/dist/checks/runner.d.ts

@@ -0,0 +1,14 @@
+import type { Check, CheckContext, AuditResult, Severity } from './types.js';
+export interface RunChecksOptions {
+    minSeverity?: Severity;
+    onCheckComplete?: (checkId: string, passed: boolean) => void;
+}
+/**
+ * Run all checks and collect findings
+ */
+export declare function runChecks(checks: Check[], ctx: CheckContext, options?: RunChecksOptions): AuditResult;
+/**
+ * Get exit code based on audit result
+ */
+export declare function getExitCode(result: AuditResult): number;
+//# sourceMappingURL=runner.d.ts.map

package/dist/checks/runner.js

@@ -0,0 +1,72 @@
+/**
+ * Run all checks and collect findings
+ */
+export function runChecks(checks, ctx, options = {}) {
+    const { minSeverity = 'LOW', onCheckComplete } = options;
+    const findings = [];
+    const passed = [];
+    const severityOrder = {
+        'HIGH': 3,
+        'MEDIUM': 2,
+        'LOW': 1,
+    };
+    const minSeverityLevel = severityOrder[minSeverity];
+    for (const check of checks) {
+        // Skip checks below minimum severity threshold
+        if (severityOrder[check.severity] < minSeverityLevel) {
+            continue;
+        }
+        try {
+            const results = check.execute(ctx);
+            if (results.length > 0) {
+                findings.push(...results);
+                if (onCheckComplete) {
+                    onCheckComplete(check.id, false);
+                }
+            }
+            else {
+                passed.push(check.id);
+                if (onCheckComplete) {
+                    onCheckComplete(check.id, true);
+                }
+            }
+        }
+        catch (error) {
+            // Check execution errors are treated as passed (fail-open for individual checks)
+            // This matches the spec: "missing config paths treated as passed"
+            passed.push(check.id);
+            if (onCheckComplete) {
+                onCheckComplete(check.id, true);
+            }
+        }
+    }
+    const summary = computeSummary(findings, passed);
+    return { findings, passed, summary };
+}
+function computeSummary(findings, passed) {
+    const high = findings.filter(f => f.severity === 'HIGH').length;
+    const medium = findings.filter(f => f.severity === 'MEDIUM').length;
+    const low = findings.filter(f => f.severity === 'LOW').length;
+    const result = findings.length > 0 ? 'FAIL' : 'PASS';
+    return {
+        total: findings.length,
+        high,
+        medium,
+        low,
+        passed: passed.length,
+        result,
+    };
+}
+/**
+ * Get exit code based on audit result
+ */
+export function getExitCode(result) {
+    if (result.summary.high > 0)
+        return 1;
+    if (result.summary.medium > 0)
+        return 2;
+    if (result.summary.low > 0)
+        return 3;
+    return 0;
+}
+//# sourceMappingURL=runner.js.map

package/dist/checks/schema.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Check validation schema
+ *
+ * Validates check definitions at load time to catch agent mistakes early.
+ * This ensures all checks follow the required pattern and naming conventions.
+ */
+import type { Check, Severity } from './types.js';
+/**
+ * Valid check categories
+ */
+export declare const VALID_CATEGORIES: readonly ["NET", "AUTH", "EXEC", "SEC", "DISC", "CHAN", "MODEL", "PLUG"];
+export type Category = typeof VALID_CATEGORIES[number];
+/**
+ * Valid severity levels
+ */
+export declare const VALID_SEVERITIES: Severity[];
+export interface ValidationError {
+    field: string;
+    message: string;
+    value?: unknown;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+/**
+ * Validate a check ID format
+ */
+export declare function validateCheckId(id: string): ValidationResult;
+/**
+ * Validate that a filename matches the check ID
+ */
+export declare function validateFilename(filename: string, checkId: string): ValidationResult;
+/**
+ * Validate a check object has all required fields
+ */
+export declare function validateCheck(check: unknown, filename?: string): ValidationResult;
+/**
+ * Format validation errors for display
+ */
+export declare function formatValidationErrors(errors: ValidationError[], filename?: string): string;
+/**
+ * Validate a check and throw if invalid
+ */
+export declare function assertValidCheck(check: unknown, filename?: string): asserts check is Check;
+/**
+ * Extract category from check ID
+ */
+export declare function getCategoryFromId(id: string): Category | null;
+/**
+ * Extract number from check ID (e.g., "001" from "NET-001")
+ */
+export declare function getNumberFromId(id: string): string | null;
+//# sourceMappingURL=schema.d.ts.map

package/dist/checks/schema.js

@@ -0,0 +1,171 @@
+/**
+ * Check validation schema
+ *
+ * Validates check definitions at load time to catch agent mistakes early.
+ * This ensures all checks follow the required pattern and naming conventions.
+ */
+/**
+ * Valid check categories
+ */
+export const VALID_CATEGORIES = ['NET', 'AUTH', 'EXEC', 'SEC', 'DISC', 'CHAN', 'MODEL', 'PLUG'];
+/**
+ * Valid severity levels
+ */
+export const VALID_SEVERITIES = ['HIGH', 'MEDIUM', 'LOW'];
+/**
+ * Check ID pattern: CAT-NNN (e.g., NET-001, AUTH-002)
+ */
+const CHECK_ID_PATTERN = /^([A-Z]+)-(\d{3})$/;
+/**
+ * Expected filename pattern: cat-nnn-description.ts (e.g., net-001-gateway-binding.ts)
+ */
+const FILENAME_PATTERN = /^([a-z]+)-(\d{3})-[a-z0-9-]+\.ts$/;
+/**
+ * Validate a check ID format
+ */
+export function validateCheckId(id) {
+    const errors = [];
+    const match = id.match(CHECK_ID_PATTERN);
+    if (!match) {
+        errors.push({
+            field: 'id',
+            message: `Check ID must match pattern CAT-NNN (e.g., NET-001). Got: ${id}`,
+            value: id,
+        });
+        return { valid: false, errors };
+    }
+    const category = match[1];
+    if (!VALID_CATEGORIES.includes(category)) {
+        errors.push({
+            field: 'id',
+            message: `Invalid category "${category}". Valid categories: ${VALID_CATEGORIES.join(', ')}`,
+            value: category,
+        });
+    }
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * Validate that a filename matches the check ID
+ */
+export function validateFilename(filename, checkId) {
+    const errors = [];
+    const match = filename.match(FILENAME_PATTERN);
+    if (!match) {
+        errors.push({
+            field: 'filename',
+            message: `Filename must match pattern cat-nnn-description.ts (e.g., net-001-gateway-binding.ts). Got: ${filename}`,
+            value: filename,
+        });
+        return { valid: false, errors };
+    }
+    // Extract category and number from filename
+    const fileCategory = match[1].toUpperCase();
+    const fileNumber = match[2];
+    // Extract from check ID
+    const idMatch = checkId.match(CHECK_ID_PATTERN);
+    if (!idMatch) {
+        // ID validation will catch this
+        return { valid: true, errors };
+    }
+    const idCategory = idMatch[1];
+    const idNumber = idMatch[2];
+    if (fileCategory !== idCategory || fileNumber !== idNumber) {
+        errors.push({
+            field: 'filename',
+            message: `Filename "${filename}" does not match check ID "${checkId}". Expected: ${idCategory.toLowerCase()}-${idNumber}-*.ts`,
+            value: filename,
+        });
+    }
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * Validate a check object has all required fields
+ */
+export function validateCheck(check, filename) {
+    const errors = [];
+    if (!check || typeof check !== 'object') {
+        errors.push({
+            field: 'check',
+            message: 'Check must be an object',
+            value: check,
+        });
+        return { valid: false, errors };
+    }
+    const c = check;
+    // Validate id
+    if (typeof c.id !== 'string' || !c.id) {
+        errors.push({
+            field: 'id',
+            message: 'Check must have a non-empty string id',
+            value: c.id,
+        });
+    }
+    else {
+        const idResult = validateCheckId(c.id);
+        errors.push(...idResult.errors);
+    }
+    // Validate severity
+    if (typeof c.severity !== 'string' || !VALID_SEVERITIES.includes(c.severity)) {
+        errors.push({
+            field: 'severity',
+            message: `Check must have a valid severity: ${VALID_SEVERITIES.join(', ')}`,
+            value: c.severity,
+        });
+    }
+    // Validate name
+    if (typeof c.name !== 'string' || !c.name) {
+        errors.push({
+            field: 'name',
+            message: 'Check must have a non-empty string name',
+            value: c.name,
+        });
+    }
+    // Validate execute function
+    if (typeof c.execute !== 'function') {
+        errors.push({
+            field: 'execute',
+            message: 'Check must have an execute function',
+            value: typeof c.execute,
+        });
+    }
+    // Validate filename matches check ID if both provided
+    if (filename && typeof c.id === 'string' && c.id) {
+        const filenameResult = validateFilename(filename, c.id);
+        errors.push(...filenameResult.errors);
+    }
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * Format validation errors for display
+ */
+export function formatValidationErrors(errors, filename) {
+    const prefix = filename ? `[${filename}] ` : '';
+    return errors.map(e => `${prefix}${e.field}: ${e.message}`).join('\n');
+}
+/**
+ * Validate a check and throw if invalid
+ */
+export function assertValidCheck(check, filename) {
+    const result = validateCheck(check, filename);
+    if (!result.valid) {
+        throw new Error(`Invalid check definition:\n${formatValidationErrors(result.errors, filename)}`);
+    }
+}
+/**
+ * Extract category from check ID
+ */
+export function getCategoryFromId(id) {
+    const match = id.match(CHECK_ID_PATTERN);
+    if (!match)
+        return null;
+    const category = match[1];
+    return VALID_CATEGORIES.includes(category) ? category : null;
+}
+/**
+ * Extract number from check ID (e.g., "001" from "NET-001")
+ */
+export function getNumberFromId(id) {
+    const match = id.match(CHECK_ID_PATTERN);
+    return match ? match[2] : null;
+}
+//# sourceMappingURL=schema.js.map

package/dist/checks/sec-001-hardcoded-keys.d.ts

@@ -0,0 +1,10 @@
+/**
+ * SEC-001: API keys hardcoded in config
+ *
+ * Detects when API keys are hardcoded directly in the configuration
+ * file instead of using environment variables.
+ */
+import type { Check } from './types.js';
+declare const check: Check;
+export default check;
+//# sourceMappingURL=sec-001-hardcoded-keys.d.ts.map

package/dist/checks/sec-001-hardcoded-keys.js

@@ -0,0 +1,34 @@
+/**
+ * SEC-001: API keys hardcoded in config
+ *
+ * Detects when API keys are hardcoded directly in the configuration
+ * file instead of using environment variables.
+ */
+import { findHardcodedApiKeys, redactValue } from '../utils.js';
+const check = {
+    id: 'SEC-001',
+    severity: 'HIGH',
+    name: 'API keys hardcoded in config',
+    execute(ctx) {
+        const found = findHardcodedApiKeys(ctx.config);
+        if (found.length > 0) {
+            return found.map(({ key, value, name }) => ({
+                id: 'SEC-001',
+                severity: 'HIGH',
+                name: 'API keys hardcoded in config',
+                location: { file: ctx.configPath, path: key },
+                currentValue: redactValue(value),
+                expectedValue: 'Use environment variable or secrets manager',
+                risk: `${name} is hardcoded in the config file. If the config is committed to version control or exposed, the key can be stolen and abused.`,
+                fix: {
+                    description: 'Move API key to environment variable',
+                    command: `# Add to .env file:\necho '${key}=${redactValue(value)}' >> ~/.clawdbot/.env\n# Remove from config:\njq 'del(.${key})' ${ctx.configPath} > tmp.json && mv tmp.json ${ctx.configPath}`,
+                },
+                references: ['https://docs.openclaw.ai/configuration/secrets'],
+            }));
+        }
+        return [];
+    },
+};
+export default check;
+//# sourceMappingURL=sec-001-hardcoded-keys.js.map

package/dist/checks/sec-002-world-readable-config.d.ts

@@ -0,0 +1,10 @@
+/**
+ * SEC-002: Configuration file is world-readable
+ *
+ * Detects when the config file has permissions that allow other users
+ * on the system to read it.
+ */
+import type { Check } from './types.js';
+declare const check: Check;
+export default check;
+//# sourceMappingURL=sec-002-world-readable-config.d.ts.map

package/dist/checks/sec-002-world-readable-config.js

@@ -0,0 +1,39 @@
+/**
+ * SEC-002: Configuration file is world-readable
+ *
+ * Detects when the config file has permissions that allow other users
+ * on the system to read it.
+ */
+import { getFileMode, formatMode } from '../utils.js';
+const check = {
+    id: 'SEC-002',
+    severity: 'HIGH',
+    name: 'Configuration file is world-readable',
+    execute(ctx) {
+        const mode = getFileMode(ctx.configPath);
+        // Skip on Windows
+        if (mode === null)
+            return [];
+        // Check if group or other has any permissions
+        const groupOther = mode & 0o077;
+        if (groupOther > 0) {
+            return [{
+                    id: 'SEC-002',
+                    severity: 'HIGH',
+                    name: 'Configuration file is world-readable',
+                    location: { file: ctx.configPath, path: null },
+                    currentValue: formatMode(mode),
+                    expectedValue: '600',
+                    risk: 'Other users on the system can read sensitive configuration including potential credentials and security settings.',
+                    fix: {
+                        description: 'Restrict file permissions',
+                        command: `chmod 600 ${ctx.configPath}`,
+                    },
+                    references: [],
+                }];
+        }
+        return [];
+    },
+};
+export default check;
+//# sourceMappingURL=sec-002-world-readable-config.js.map

package/dist/checks/sec-003-credentials-exposed.d.ts

@@ -0,0 +1,10 @@
+/**
+ * SEC-003: Credentials directory exposed
+ *
+ * Detects when the credentials directory has permissions that allow
+ * other users on the system to access it.
+ */
+import type { Check } from './types.js';
+declare const check: Check;
+export default check;
+//# sourceMappingURL=sec-003-credentials-exposed.d.ts.map

package/dist/checks/sec-003-credentials-exposed.js

@@ -0,0 +1,41 @@
+/**
+ * SEC-003: Credentials directory exposed
+ *
+ * Detects when the credentials directory has permissions that allow
+ * other users on the system to access it.
+ */
+import { getFileMode, formatMode } from '../utils.js';
+import { join } from 'node:path';
+const check = {
+    id: 'SEC-003',
+    severity: 'HIGH',
+    name: 'Credentials directory exposed',
+    execute(ctx) {
+        const credentialsDir = join(ctx.configDir, 'credentials');
+        const mode = getFileMode(credentialsDir);
+        // Skip on Windows or if dir doesn't exist
+        if (mode === null)
+            return [];
+        // Check if group or other has any permissions
+        const groupOther = mode & 0o077;
+        if (groupOther > 0) {
+            return [{
+                    id: 'SEC-003',
+                    severity: 'HIGH',
+                    name: 'Credentials directory exposed',
+                    location: { file: credentialsDir, path: null },
+                    currentValue: formatMode(mode),
+                    expectedValue: '700',
+                    risk: 'Other users on the system can access the credentials directory, potentially reading or modifying stored credentials.',
+                    fix: {
+                        description: 'Restrict directory permissions',
+                        command: `chmod 700 ${credentialsDir}`,
+                    },
+                    references: [],
+                }];
+        }
+        return [];
+    },
+};
+export default check;
+//# sourceMappingURL=sec-003-credentials-exposed.js.map

package/dist/checks/sec-004-env-readable.d.ts

@@ -0,0 +1,10 @@
+/**
+ * SEC-004: .env file is readable by other users
+ *
+ * Detects when the .env file has permissions that allow other users
+ * on the system to read it.
+ */
+import type { Check } from './types.js';
+declare const check: Check;
+export default check;
+//# sourceMappingURL=sec-004-env-readable.d.ts.map

package/dist/checks/sec-004-env-readable.js

@@ -0,0 +1,40 @@
+/**
+ * SEC-004: .env file is readable by other users
+ *
+ * Detects when the .env file has permissions that allow other users
+ * on the system to read it.
+ */
+import { getFileMode, formatMode } from '../utils.js';
+import { join } from 'node:path';
+const check = {
+    id: 'SEC-004',
+    severity: 'MEDIUM',
+    name: '.env file is readable by other users',
+    execute(ctx) {
+        const envPath = join(ctx.configDir, '.env');
+        const mode = getFileMode(envPath);
+        // Skip on Windows or if file doesn't exist
+        if (mode === null)
+            return [];
+        const groupOther = mode & 0o077;
+        if (groupOther > 0) {
+            return [{
+                    id: 'SEC-004',
+                    severity: 'MEDIUM',
+                    name: '.env file is readable by other users',
+                    location: { file: envPath, path: null },
+                    currentValue: formatMode(mode),
+                    expectedValue: '600',
+                    risk: 'The .env file may contain API keys and secrets. Other users on the system can read these credentials.',
+                    fix: {
+                        description: 'Restrict file permissions',
+                        command: `chmod 600 ${envPath}`,
+                    },
+                    references: [],
+                }];
+        }
+        return [];
+    },
+};
+export default check;
+//# sourceMappingURL=sec-004-env-readable.js.map

package/dist/checks/sec-005-transcripts-exposed.d.ts

@@ -0,0 +1,11 @@
+/**
+ * SEC-005: Session transcripts exposed
+ *
+ * Detects when the sessions directory in ~/.clawdbot/agents/<agent>/sessions/
+ * has permissions other than 700, potentially exposing conversation data.
+ * Checking directory permissions is more efficient than checking individual files.
+ */
+import type { Check } from './types.js';
+declare const check: Check;
+export default check;
+//# sourceMappingURL=sec-005-transcripts-exposed.d.ts.map

package/dist/checks/sec-005-transcripts-exposed.js

@@ -0,0 +1,62 @@
+/**
+ * SEC-005: Session transcripts exposed
+ *
+ * Detects when the sessions directory in ~/.clawdbot/agents/<agent>/sessions/
+ * has permissions other than 700, potentially exposing conversation data.
+ * Checking directory permissions is more efficient than checking individual files.
+ */
+import { getFileMode, formatMode } from '../utils.js';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { existsSync, readdirSync } from 'node:fs';
+const check = {
+    id: 'SEC-005',
+    severity: 'MEDIUM',
+    name: 'Session transcripts exposed',
+    execute(ctx) {
+        const findings = [];
+        const agentsDir = join(homedir(), '.clawdbot', 'agents');
+        // Skip if agents directory doesn't exist
+        if (!existsSync(agentsDir))
+            return [];
+        let agentDirs;
+        try {
+            agentDirs = readdirSync(agentsDir, { withFileTypes: true })
+                .filter(d => d.isDirectory())
+                .map(d => d.name);
+        }
+        catch {
+            return [];
+        }
+        for (const agentName of agentDirs) {
+            const sessionsDir = join(agentsDir, agentName, 'sessions');
+            if (!existsSync(sessionsDir))
+                continue;
+            const mode = getFileMode(sessionsDir);
+            // Skip on Windows
+            if (mode === null)
+                continue;
+            // Check if group or other has any permissions (should be 700)
+            const groupOther = mode & 0o077;
+            if (groupOther > 0) {
+                findings.push({
+                    id: 'SEC-005',
+                    severity: 'MEDIUM',
+                    name: 'Session transcripts exposed',
+                    location: { file: sessionsDir, path: null },
+                    currentValue: formatMode(mode),
+                    expectedValue: '700',
+                    risk: 'Sessions directory is accessible by other users. This directory contains conversation history which may include sensitive information.',
+                    fix: {
+                        description: 'Restrict directory permissions',
+                        command: `chmod 700 "${sessionsDir}"`,
+                    },
+                    references: ['https://docs.openclaw.ai/security#transcript-protection'],
+                });
+            }
+        }
+        return findings;
+    },
+};
+export default check;
+//# sourceMappingURL=sec-005-transcripts-exposed.js.map

package/dist/checks/sec-006-redaction-disabled.d.ts

@@ -0,0 +1,10 @@
+/**
+ * SEC-006: Log redaction disabled
+ *
+ * Detects when logging.redactSensitive is set to 'off',
+ * allowing sensitive information to appear in logs.
+ */
+import type { Check } from './types.js';
+declare const check: Check;
+export default check;
+//# sourceMappingURL=sec-006-redaction-disabled.d.ts.map

package/dist/checks/sec-006-redaction-disabled.js

@@ -0,0 +1,34 @@
+/**
+ * SEC-006: Log redaction disabled
+ *
+ * Detects when logging.redactSensitive is set to 'off',
+ * allowing sensitive information to appear in logs.
+ */
+import { getValueAtPath } from '../utils.js';
+const check = {
+    id: 'SEC-006',
+    severity: 'LOW',
+    name: 'Log redaction disabled',
+    execute(ctx) {
+        const redactSensitive = getValueAtPath(ctx.config, 'logging.redactSensitive');
+        if (redactSensitive === 'off' || redactSensitive === false) {
+            return [{
+                    id: 'SEC-006',
+                    severity: 'LOW',
+                    name: 'Log redaction disabled',
+                    location: { file: ctx.configPath, path: 'logging.redactSensitive' },
+                    currentValue: redactSensitive,
+                    expectedValue: 'on (or not set)',
+                    risk: 'Sensitive information such as API keys, tokens, and personal data may appear in logs unredacted, potentially exposing secrets.',
+                    fix: {
+                        description: 'Enable log redaction',
+                        command: `jq '.logging.redactSensitive = "on"' ${ctx.configPath} > tmp.json && mv tmp.json ${ctx.configPath}`,
+                    },
+                    references: ['https://docs.openclaw.ai/logging/security#redaction'],
+                }];
+        }
+        return [];
+    },
+};
+export default check;
+//# sourceMappingURL=sec-006-redaction-disabled.js.map

package/dist/checks/sec-007-no-redact-patterns.d.ts

@@ -0,0 +1,10 @@
+/**
+ * SEC-007: No custom redact patterns
+ *
+ * Detects when logging.redactPatterns is empty or not configured,
+ * relying only on built-in redaction patterns.
+ */
+import type { Check } from './types.js';
+declare const check: Check;
+export default check;
+//# sourceMappingURL=sec-007-no-redact-patterns.d.ts.map