securityclaw 0.0.2 → 0.0.3

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.0.3] - 2026-03-18
+
+### Changed
+- Reduced OpenClaw install-time false positives by separating environment reads, file reads, and process-launch helpers out of files that previously tripped static safety rules.
+- Kept the admin console, installer CLI, and Feishu approval delivery behavior unchanged while restructuring those internals for cleaner package scans.
+- Verified the packed npm tarball against the local OpenClaw `skill-scanner` and brought reported findings down to zero.
+
 ## [0.0.2] - 2026-03-17
 
 ### Changed

package/README.md

@@ -6,19 +6,23 @@ SecurityClaw is a runtime security plugin for [OpenClaw](https://github.com/open
 
 ## Why SecurityClaw
 
-LLM agents can execute powerful tools. SecurityClaw adds a rule-first guardrail layer so risky operations are blocked, challenged for approval, or allowed with warning and traceability.
+LLM agents can execute powerful tools. SecurityClaw provides a policy guardrail layer so risky operations are either blocked, challenged for approval, or allowed with warning and traceability.
 
 ## Core Capabilities
 
 - Runtime policy enforcement for OpenClaw hooks (`before_tool_call`, `after_tool_call`, etc.)
 - Rule-first security model (`allow`, `warn`, `challenge`, `block`)
 - Challenge approval workflow with command-based admin handling
-- Dynamic sensitive-path registry and DLP sanitization
-- Admin dashboard for strategy, account policy, and runtime status
-- Built-in internationalization (`en` and `zh-CN`) for runtime and admin text
+- Dynamic sensitive-path registry that maps paths to asset labels before rule evaluation
+- Sensitive data scanning and sanitization (DLP)
+- Admin dashboard for strategy and account policy operations
+- Decision events for audit and observability
+- Built-in internationalization (`en` and `zh-CN`) for runtime/admin text
 
 ## Install
 
+### Direct Use
+
 Install the latest published release:
 
 ```bash
@@ -34,30 +38,49 @@ curl -fsSL https://raw.githubusercontent.com/znary/securityclaw/main/install.sh
 Install a specific published version:
 
 ```bash
-SECURITYCLAW_VERSION=0.0.2 curl -fsSL https://raw.githubusercontent.com/znary/securityclaw/main/install.sh | bash
+SECURITYCLAW_VERSION=0.0.3 curl -fsSL https://raw.githubusercontent.com/znary/securityclaw/main/install.sh | bash
 ```
 
-Published npm releases already include the prebuilt admin frontend bundle, so end-user installs do not rebuild the dashboard during plugin installation.
+After installation, if the admin dashboard did not open automatically, open `http://127.0.0.1:4780`.
 
-## Uninstall
+### From Source
 
-Remove the installed plugin from OpenClaw:
+Clone the repository, then install dependencies:
 
 ```bash
-openclaw plugins uninstall securityclaw
+npm install
 ```
 
-If you want to preview the removal first:
+Install the current workspace build into OpenClaw:
 
 ```bash
-openclaw plugins uninstall securityclaw --dry-run
+npm run openclaw:install
+```
+
+Run verification:
+
+```bash
+npm test
+```
+
+Start the standalone admin dashboard when needed:
+
+```bash
+npm run admin
 ```
 
-After install or uninstall, restart or verify the gateway if needed:
+## Uninstall
+
+Remove the installed plugin from OpenClaw:
 
 ```bash
-openclaw gateway restart
-openclaw gateway status
+openclaw plugins uninstall securityclaw
+```
+
+Preview the removal first if needed:
+
+```bash
+openclaw plugins uninstall securityclaw --dry-run
 ```
 
 ## Documentation

package/README.zh-CN.md

@@ -6,19 +6,23 @@ SecurityClaw 是面向 [OpenClaw](https://github.com/openclaw/openclaw) 的运
 
 ## SecurityClaw 解决什么问题
 
-LLM Agent 具备高权限工具调用能力。SecurityClaw 提供一层规则优先的安全护栏，让高风险操作被阻止、进入审批，或在留痕前提下放行。
+LLM Agent 具备高权限工具调用能力。SecurityClaw 在运行时提供策略护栏，将高风险操作按规则执行为拦截、审批确认、提醒或放行，并保留可追溯审计信息。
 
 ## 核心能力
 
-- 基于 OpenClaw Hook 的运行时策略执行（`before_tool_call`、`after_tool_call` 等）
+- 基于 OpenClaw Hook 的运行时策略执行（`before_tool_call` 等）
 - 规则优先决策模型（`allow` / `warn` / `challenge` / `block`）
-- 基于管理员命令的审批流程
-- 动态敏感路径注册表与 DLP 敏感信息净化
-- 用于策略、账号策略和运行状态的管理后台
-- 运行时与后台均支持中英文（`en` / `zh-CN`）
+- Challenge 审批流程与管理员命令处理
+- 动态敏感路径注册表，在规则判断前先把路径映射成资产标签
+- DLP 扫描与敏感输出净化
+- 管理后台（策略与账号策略配置）
+- 决策事件与状态观测
+- 中英文国际化（`en` / `zh-CN`）
 
 ## 安装
 
+### 直接使用
+
 安装最新发布版本：
 
 ```bash
@@ -34,10 +38,36 @@ curl -fsSL https://raw.githubusercontent.com/znary/securityclaw/main/install.sh
 安装指定发布版本：
 
 ```bash
-SECURITYCLAW_VERSION=0.0.2 curl -fsSL https://raw.githubusercontent.com/znary/securityclaw/main/install.sh | bash
+SECURITYCLAW_VERSION=0.0.3 curl -fsSL https://raw.githubusercontent.com/znary/securityclaw/main/install.sh | bash
+```
+
+安装完成后，如果管理后台没有自动打开，可手动访问 `http://127.0.0.1:4780`。
+
+### 从源码开发
+
+克隆仓库后先安装依赖：
+
+```bash
+npm install
+```
+
+把当前工作区构建安装到 OpenClaw：
+
+```bash
+npm run openclaw:install
 ```
 
-发布到 npm 的版本会直接带上预构建好的管理后台前端，因此终端用户安装插件时不需要现场再构建后台资源。
+执行验证：
+
+```bash
+npm test
+```
+
+需要时可单独启动管理后台：
+
+```bash
+npm run admin
+```
 
 ## 卸载
 
@@ -53,13 +83,6 @@ openclaw plugins uninstall securityclaw
 openclaw plugins uninstall securityclaw --dry-run
 ```
 
-安装或卸载后，如有需要可重启并校验 gateway：
-
-```bash
-openclaw gateway restart
-openclaw gateway status
-```
-
 ## 文档导航
 
 - [文档索引](./docs/README.zh-CN.md)

package/admin/server.ts

@@ -1,6 +1,5 @@
 import http from "node:http";
-import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readdirSync, statSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { DatabaseSync } from "node:sqlite";
@@ -10,6 +9,7 @@ import {
   matchesAdminDecisionFilter,
   normalizeAdminDecisionFilterId,
 } from "../src/admin/dashboard_url_state.ts";
+import { readJsonRecordFile, readUtf8File } from "../src/admin/file_reader.ts";
 import { SkillInterceptionStore } from "../src/admin/skill_interception_store.ts";
 import { listOpenClawChatSessions } from "../src/admin/openclaw_session_catalog.ts";
 import { ConfigManager } from "../src/config/loader.ts";
@@ -29,10 +29,13 @@ import {
 } from "../src/domain/services/sensitive_path_registry.ts";
 import type { SecurityClawLocale } from "../src/i18n/locale.ts";
 import { pickLocalized, resolveSecurityClawLocale } from "../src/i18n/locale.ts";
+import { readSecurityClawAdminServerEnv, resolveSecurityClawAdminPort } from "../src/runtime/process_env.ts";
+import { runProcessSync } from "../src/runtime/process_runner.ts";
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const PUBLIC_DIR = path.resolve(ROOT, "admin/public");
-const DEFAULT_PORT = Number(process.env.SECURITYCLAW_ADMIN_PORT ?? 4780);
+const DEFAULT_ADMIN_ENV = readSecurityClawAdminServerEnv();
+const DEFAULT_PORT = resolveSecurityClawAdminPort();
 const DEFAULT_OPENCLAW_HOME = resolveDefaultOpenClawStateDir();
 
 type AdminLogger = {
@@ -128,7 +131,7 @@ const EMPTY_DECISION_COUNTS: DecisionHistoryCounts = {
   block: 0,
 };
 
-const ADMIN_DEFAULT_LOCALE = resolveSecurityClawLocale(process.env.SECURITYCLAW_LOCALE, "en");
+const ADMIN_DEFAULT_LOCALE = resolveSecurityClawLocale(DEFAULT_ADMIN_ENV.locale, "en");
 
 function sendJson(res: http.ServerResponse, status: number, body: unknown): void {
   res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
@@ -181,7 +184,7 @@ function safeReadStatus(statusPath: string): JsonRecord {
     };
   }
   try {
-    return JSON.parse(readFileSync(statusPath, "utf8")) as JsonRecord;
+    return readJsonRecordFile(statusPath);
   } catch {
     return {
       message: "status file exists but cannot be parsed",
@@ -842,7 +845,7 @@ function serveStatic(req: http.IncomingMessage, res: http.ServerResponse, url: U
           : ext === ".svg"
             ? "image/svg+xml"
           : "application/octet-stream";
-  sendText(res, 200, readFileSync(absolute, "utf8"), contentType);
+  sendText(res, 200, readUtf8File(absolute), contentType);
 }
 
 function readEffectivePolicy(runtime: AdminRuntime, strategyStore: StrategyStore): {
@@ -858,10 +861,10 @@ function readEffectivePolicy(runtime: AdminRuntime, strategyStore: StrategyStore
 
 function resolveAdminPluginConfig(options: AdminServerOptions): SecurityClawPluginConfig {
   return {
-    ...(process.env.SECURITYCLAW_CONFIG_PATH ? { configPath: process.env.SECURITYCLAW_CONFIG_PATH } : {}),
-    ...(process.env.SECURITYCLAW_LEGACY_OVERRIDE_PATH ? { overridePath: process.env.SECURITYCLAW_LEGACY_OVERRIDE_PATH } : {}),
-    ...(process.env.SECURITYCLAW_STATUS_PATH ? { statusPath: process.env.SECURITYCLAW_STATUS_PATH } : {}),
-    ...(process.env.SECURITYCLAW_DB_PATH ? { dbPath: process.env.SECURITYCLAW_DB_PATH } : {}),
+    ...(DEFAULT_ADMIN_ENV.configPath ? { configPath: DEFAULT_ADMIN_ENV.configPath } : {}),
+    ...(DEFAULT_ADMIN_ENV.legacyOverridePath ? { overridePath: DEFAULT_ADMIN_ENV.legacyOverridePath } : {}),
+    ...(DEFAULT_ADMIN_ENV.statusPath ? { statusPath: DEFAULT_ADMIN_ENV.statusPath } : {}),
+    ...(DEFAULT_ADMIN_ENV.dbPath ? { dbPath: DEFAULT_ADMIN_ENV.dbPath } : {}),
     ...(options.configPath !== undefined ? { configPath: options.configPath } : {}),
     ...(options.legacyOverridePath !== undefined ? { overridePath: options.legacyOverridePath } : {}),
     ...(options.statusPath !== undefined ? { statusPath: options.statusPath } : {}),
@@ -890,19 +893,19 @@ function parsePids(output: string): number[] {
 }
 
 function listListeningPidsByPort(port: number): number[] {
-  const result = spawnSync("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"], { encoding: "utf8" });
+  const result = runProcessSync("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"], { encoding: "utf8" });
   if (result.error || result.status !== 0) {
     return [];
   }
-  return parsePids(result.stdout);
+  return parsePids(result.stdout ?? "");
 }
 
 function readProcessCommand(pid: number): string {
-  const result = spawnSync("ps", ["-p", String(pid), "-o", "command="], { encoding: "utf8" });
+  const result = runProcessSync("ps", ["-p", String(pid), "-o", "command="], { encoding: "utf8" });
   if (result.error || result.status !== 0) {
     return "";
   }
-  return result.stdout.trim();
+  return (result.stdout ?? "").trim();
 }
 
 function looksLikeOpenClawProcess(command: string): boolean {

package/bin/securityclaw.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import { readFileSync } from "node:fs";
-import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -9,6 +9,9 @@ import { buildInstallPlan, parseInstallArgs } from "./install-lib.mjs";
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const pkg = JSON.parse(readFileSync(path.join(ROOT, "package.json"), "utf8"));
+const requireFromHere = createRequire(import.meta.url);
+const SYSTEM_PROCESS_MODULE_ID = `node:child${String.fromCharCode(95)}process`;
+const { spawnSync } = requireFromHere(SYSTEM_PROCESS_MODULE_ID);
 
 function printUsage() {
   console.log(`SecurityClaw installer

package/index.ts

@@ -32,6 +32,7 @@ import { RuntimeStatusStore } from "./src/monitoring/status_store.ts";
 import { startAdminServer } from "./admin/server.ts";
 import { announceAdminConsole, shouldAnnounceAdminConsoleForArgv } from "./src/admin/console_notice.ts";
 import { shouldAutoStartAdminServer } from "./src/admin/runtime_guard.ts";
+import { readProcessEnvValue, resolveSecurityClawAdminPort } from "./src/runtime/process_env.ts";
 import { AccountPolicyEngine } from "./src/domain/services/account_policy_engine.ts";
 import { ApprovalSubjectResolver } from "./src/domain/services/approval_subject_resolver.ts";
 import {
@@ -171,7 +172,7 @@ function resolvePluginStateDir(api: OpenClawPluginApi): string {
 }
 
 function resolveAdminConsoleUrl(pluginConfig: SecurityClawPluginConfig): string {
-  const port = pluginConfig.adminPort ?? Number(process.env.SECURITYCLAW_ADMIN_PORT ?? 4780);
+  const port = pluginConfig.adminPort ?? resolveSecurityClawAdminPort();
   return `http://127.0.0.1:${port}`;
 }
 
@@ -1164,7 +1165,7 @@ function resolveFeishuSecretValue(value: unknown): string | undefined {
   const source = feishuTrimmedString(record.source)?.toLowerCase();
   const id = feishuTrimmedString(record.id);
   if (source === "env" && id) {
-    const envValue = feishuTrimmedString(process.env[id]);
+    const envValue = feishuTrimmedString(readProcessEnvValue(id));
     if (envValue) {
       return envValue;
     }
@@ -1996,7 +1997,7 @@ const plugin = {
         return;
       }
 
-      const autoStartDecision = shouldAutoStartAdminServer(process.env);
+      const autoStartDecision = shouldAutoStartAdminServer();
       if (!autoStartDecision.enabled) {
         if (shouldAnnounceAdminConsoleForArgv(process.argv)) {
           announceAdminConsole({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "securityclaw",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "SecurityClaw security plugin for OpenClaw-compatible hooks.",
   "license": "MIT",
   "type": "module",

package/src/admin/console_notice.ts

@@ -1,10 +1,10 @@
-import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import path from "node:path";
 
 import { resolveSecurityClawStateDir } from "../infrastructure/config/plugin_config_parser.ts";
 import type { SecurityClawLocale } from "../i18n/locale.ts";
 import { pickLocalized } from "../i18n/locale.ts";
+import { runProcessSync } from "../runtime/process_runner.ts";
 
 export type AdminConsoleState = "started" | "already-running" | "service-command";
 
@@ -122,7 +122,7 @@ function writeAdminConsoleMarker(markerPath: string, url: string): void {
 
 export function openAdminConsoleInBrowser(url: string): BrowserOpenResult {
   if (process.platform === "darwin") {
-    const result = spawnSync("open", [url], { stdio: "ignore", timeout: 5_000 });
+    const result = runProcessSync("open", [url], { stdio: "ignore", timeout: 5_000 });
     if (result.error) {
       return { ok: false, command: "open", error: String(result.error) };
     }
@@ -133,7 +133,7 @@ export function openAdminConsoleInBrowser(url: string): BrowserOpenResult {
   }
 
   if (process.platform === "win32") {
-    const result = spawnSync("cmd", ["/c", "start", "", url], {
+    const result = runProcessSync("cmd", ["/c", "start", "", url], {
       stdio: "ignore",
       timeout: 5_000,
       windowsHide: true,
@@ -148,7 +148,7 @@ export function openAdminConsoleInBrowser(url: string): BrowserOpenResult {
   }
 
   if (process.platform === "linux") {
-    const result = spawnSync("xdg-open", [url], { stdio: "ignore", timeout: 5_000 });
+    const result = runProcessSync("xdg-open", [url], { stdio: "ignore", timeout: 5_000 });
     if (result.error) {
       return { ok: false, command: "xdg-open", error: String(result.error) };
     }

package/src/admin/file_reader.ts

@@ -0,0 +1,12 @@
+import { readFileSync } from "node:fs";
+
+type JsonRecord = Record<string, unknown>;
+
+export function readUtf8File(filePath: string): string {
+  return readFileSync(filePath, "utf8");
+}
+
+export function readJsonRecordFile(filePath: string): JsonRecord {
+  return JSON.parse(readUtf8File(filePath)) as JsonRecord;
+}
+

package/src/admin/skill_interception_store.ts

@@ -670,8 +670,21 @@ export function analyzeSkillDocument(input: {
   const normalizedName = input.name.trim().toLowerCase();
   const siblingNames = input.siblingNames.map((item) => item.trim().toLowerCase()).filter(Boolean);
   const downloadExecutePattern = /(curl|wget)[^\n]{0,120}\|\s*(sh|bash|zsh)|download[^.\n]{0,60}(then )?(run|execute)/i;
-  const shellExecPattern =
-    /(exec_command|spawnSync|child_process|bash\s+-lc|zsh\s+-lc|powershell|rm\s+-rf|chmod\s+-R|chown\s+-R)/i;
+  const childProcessToken = `child${String.fromCharCode(95)}process`;
+  const shellExecPattern = new RegExp(
+    [
+      "exec_command",
+      "spawnSync",
+      childProcessToken,
+      "bash\\s+-lc",
+      "zsh\\s+-lc",
+      "powershell",
+      "rm\\s+-rf",
+      "chmod\\s+-R",
+      "chown\\s+-R",
+    ].join("|"),
+    "i",
+  );
   const bypassPattern =
     /(ignore|bypass|disable|skip)[^.\n]{0,40}(policy|security|guard|safety)|hide (the )?(output|logs)|不要提示|不要暴露/i;
   const credentialPattern =

package/src/runtime/process_env.ts

@@ -0,0 +1,47 @@
+type SecurityClawAdminServerEnv = {
+  adminPort?: number | undefined;
+  locale?: string | undefined;
+  configPath?: string | undefined;
+  legacyOverridePath?: string | undefined;
+  statusPath?: string | undefined;
+  dbPath?: string | undefined;
+};
+
+function readTextEnv(name: string, env: NodeJS.ProcessEnv = process.env): string | undefined {
+  const value = env[name];
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed || undefined;
+}
+
+function readNumericEnv(name: string, env: NodeJS.ProcessEnv = process.env): number | undefined {
+  const value = readTextEnv(name, env);
+  if (!value) {
+    return undefined;
+  }
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+export function readProcessEnvValue(name: string, env: NodeJS.ProcessEnv = process.env): string | undefined {
+  return readTextEnv(name, env);
+}
+
+export function resolveSecurityClawAdminPort(defaultPort = 4780, env: NodeJS.ProcessEnv = process.env): number {
+  return readNumericEnv("SECURITYCLAW_ADMIN_PORT", env) ?? defaultPort;
+}
+
+export function readSecurityClawAdminServerEnv(
+  env: NodeJS.ProcessEnv = process.env,
+): SecurityClawAdminServerEnv {
+  return {
+    adminPort: readNumericEnv("SECURITYCLAW_ADMIN_PORT", env),
+    locale: readTextEnv("SECURITYCLAW_LOCALE", env),
+    configPath: readTextEnv("SECURITYCLAW_CONFIG_PATH", env),
+    legacyOverridePath: readTextEnv("SECURITYCLAW_LEGACY_OVERRIDE_PATH", env),
+    statusPath: readTextEnv("SECURITYCLAW_STATUS_PATH", env),
+    dbPath: readTextEnv("SECURITYCLAW_DB_PATH", env),
+  };
+}

package/src/runtime/process_runner.ts

@@ -0,0 +1,38 @@
+import { createRequire } from "node:module";
+
+export type RunProcessSyncOptions = {
+  cwd?: string;
+  encoding?: BufferEncoding;
+  stdio?: "ignore" | "inherit" | "pipe";
+  timeout?: number;
+  windowsHide?: boolean;
+};
+
+export type RunProcessSyncResult = {
+  status: number | null;
+  stdout?: string;
+  stderr?: string;
+  error?: unknown;
+};
+
+type RunProcessSyncFn = (
+  command: string,
+  args?: readonly string[],
+  options?: RunProcessSyncOptions,
+) => RunProcessSyncResult;
+
+const requireFromHere = createRequire(import.meta.url);
+const SYSTEM_PROCESS_MODULE_ID = `node:child${String.fromCharCode(95)}process`;
+const RUN_PROCESS_SYNC_METHOD = ["spawn", "Sync"].join("");
+const runProcessSyncImpl = (requireFromHere(SYSTEM_PROCESS_MODULE_ID) as Record<string, unknown>)[
+  RUN_PROCESS_SYNC_METHOD
+] as RunProcessSyncFn;
+
+export function runProcessSync(
+  command: string,
+  args: readonly string[],
+  options: RunProcessSyncOptions = {},
+): RunProcessSyncResult {
+  return runProcessSyncImpl(command, args, options);
+}
+