<!-- source: https://deepwiki.com/openclaw/openclaw/7.2-security-audit-system -->

# Security Audit System

- docs/cli/update.md
- docs/gateway/security/index.md
- docs/gateway/security/shrinkwrap.md
- docs/install/development-channels.md
- docs/install/index.md
- docs/install/installer.md
- docs/install/updating.md
- docs/plugins/dependency-resolution.md
- docs/reference/release-performance-sweep.md
- extensions/acpx/package.json
- extensions/codex/package.json
- extensions/codex/src/app-server/attempt-startup.ts
- extensions/tlon/package.json
- scripts/install-cli.sh
- scripts/install.ps1
- scripts/install.sh
- scripts/lib/plugin-npm-package-manifest.mjs
- src/agents/openai-routing.test.ts
- src/agents/openai-routing.ts
- src/cli/update-cli.test.ts
- src/cli/update-cli/update-command.ts
- src/commands/agent-command.test-mocks.ts
- src/commands/doctor-disk-space.test.ts
- src/commands/doctor-disk-space.ts
- src/commands/doctor-lint.test.ts
- src/commands/doctor/shared/codex-route-warnings.test.ts
- src/commands/doctor/shared/codex-route-warnings.ts
- src/commands/doctor/shared/stale-plugin-config.test.ts
- src/commands/doctor/shared/stale-plugin-config.ts
- src/config/codex-plugin-diagnostics.ts
- src/config/config.plugin-validation.test.ts
- src/config/validation.ts
- src/flows/doctor-core-checks.test.ts
- src/flows/doctor-core-checks.ts
- src/flows/doctor-health-contributions.test.ts
- src/flows/doctor-health-contributions.ts
- src/flows/doctor-health-conversion-plan.ts
- src/flows/doctor-lint-flow.ts
- src/infra/install-source-utils.test.ts
- src/infra/install-source-utils.ts
- src/infra/npm-install-env.test.ts
- src/infra/npm-install-env.ts
- src/infra/safe-package-install.test.ts
- src/infra/update-channels.test.ts
- src/infra/update-channels.ts
- src/infra/update-global.test.ts
- src/infra/update-global.ts
- src/infra/update-runner.test.ts
- src/infra/update-runner.ts
- src/scripts/test-live-media.test.ts
- test/plugin-npm-package-manifest.test.ts
- test/scripts/install-cli.test.ts
- test/scripts/install-ps1.test.ts
- test/scripts/install-sh.test.ts

The Security Audit System in OpenClaw performs automated security checks that assess deployment configurations, plugin integrity, and runtime state to identify risks, misconfigurations, and potential vulnerabilities. It helps maintain a secure personal AI assistant by analyzing key security surfaces such as the filesystem, Gateway exposure, sandbox configurations, and tool policies. The system classifies findings by severity and supports auto-fixing common security footguns where safe.

## Command Interface

The security audit system is primarily invoked via the CLI command:

```

```

- Basic Mode : Runs configuration and filesystem checks based on the local openclaw.json and state directory.
- --deep : Adds live probing of the Gateway, inspection of runtime artifacts like Docker containers, and scanning of system services for extra gateway installs.
- --fix : Attempts to auto-remediate specific categories of security issues safely, such as tightening permissions and restoring sensitive logging redaction.
- --json : Produces a machine-readable JSON report suitable for automation or continuous integration.

The system is deeply integrated into the `openclaw doctor` command via `DoctorHealthContribution` entries [src/flows/doctor-health-contributions.ts48-53](https://github.com/openclaw/openclaw/blob/fbdf5937/src/flows/doctor-health-contributions.ts#L48-L53) These contributions register specific health checks (e.g., `core/doctor/ui-protocol-freshness`) that identify issues like ambiguous auth modes or missing owner accounts [src/flows/doctor-health-contributions.ts135-161](https://github.com/openclaw/openclaw/blob/fbdf5937/src/flows/doctor-health-contributions.ts#L135-L161)

**Sources:**

- src/flows/doctor-health-contributions.ts 48-53
- src/flows/doctor-health-contributions.ts 135-161

## Severity Levels and Finding Categories

Findings are classified into three severity levels: `info`, `warning`, and `error`. The system organizes checks into several key categories.

### 1. Gateway & Auth Exposure

Validates the security posture of the Gateway control plane.

- Auth Mode Ambiguity : Flags when gateway.auth.token and gateway.auth.password are both configured while gateway.auth.mode is unset src/flows/doctor-health-contributions.ts 150-160
- Owner Account Configuration : Warns if the Gateway mode is unset, which blocks startup, or if setup has not been completed src/flows/doctor-health-contributions.ts 139-149
- Auth Profile Health : Repairs legacy flat auth profile stores and canonical API key field aliases src/flows/doctor-health-contributions.ts 163-182

### 2. Filesystem & Secret Management

Ensures that sensitive data is protected at rest.

- Legacy OAuth Migration : Identifies and repairs legacy OAuth profile IDs and sidecar profiles src/flows/doctor-health-contributions.ts 166-170
- Config Persistence : Ensures the configuration is writable and valid before attempting persistence src/flows/doctor-health-contributions.ts 21-30

### 3. Plugin & Extension Security

Audits the integrity of installed extensions and their configuration.

- Plugin Registry Integrity : Validates the plugin registry after configuration mutations src/cli/update-cli/update-command.ts 119
- Official External Plugins : Identifies missing official external plugins and provides installation hints src/config/validation.ts 185-194
- Stale Config Cleanup : Detects removed plugins and ignores stale configuration entries in plugins.allow or plugins.slots src/config/config.plugin-validation.test.ts 78-91

### 4. Tool & Sandbox Policy

- Safe Directory Execution : On Windows, the system ensures commands are invoked from safe directories to prevent path-based attacks test/scripts/install-ps1.test.ts 116-127
- Codex Route Security : Identifies legacy openai-codex/* model refs that should be rewritten to openai/* to align with modern runtime policies src/commands/doctor/shared/codex-route-warnings.test.ts 57-75
- App-Server Sanitization : Warns when Codex app-server commands include inline arguments, which should be moved to the args field for proper escaping src/commands/doctor/shared/codex-route-warnings.test.ts 137-163

**Sources:**

- src/flows/doctor-health-contributions.ts 135-182
- src/config/validation.ts 185-194
- src/config/config.plugin-validation.test.ts 78-91
- test/scripts/install-ps1.test.ts 116-127
- src/commands/doctor/shared/codex-route-warnings.test.ts 57-163

## Audit Data Flow Diagram

This diagram maps the audit process to the internal `Doctor` health flow and configuration validation logic.

"Natural Language Space" to "Code Entity Space" Mapping:

```

```

**Sources:**

- src/cli/update-cli/update-command.ts 16-24
- src/flows/doctor-health-contributions.ts 100-120
- src/flows/doctor-health-contributions.test.ts 48-50

## Implementation Entity Mapping

This diagram bridges the security categories to the specific code entities responsible for probing and repairing them.

```

```

**Sources:**

- src/flows/doctor-health-contributions.ts 135
- src/cli/update-cli/update-command.ts 97
- src/commands/doctor/shared/codex-route-warnings.ts 34
- src/config/config.plugin-validation.test.ts 7

## Auto-Fix Capabilities

The `--fix` flag (or `openclaw doctor --fix`) enables the **Auto-Fix System**, which automates remediation of detected security issues.

1. Auth Profile Repair : Automatically repairs legacy flat auth profile stores and migrates OAuth profile IDs src/flows/doctor-health-contributions.ts 164-170
2. Plugin Synchronization : Syncs plugins for the current update channel and updates NPM-installed plugins to secure versions src/cli/update-cli/update-command.ts 97-98
3. Config Remediation : Replaces corrupted or invalid configuration files with snapshots or repairs legacy fields src/cli/update-cli/update-command.ts 115-116
4. Codex Route Migration : Rewrites legacy model references and repairs session store routes to use canonical OpenAI providers src/commands/doctor/shared/codex-route-warnings.ts 35-37
5. Installer Hardening : The install.sh script enforces noninteractive modes for package managers and validates checksums for bootstrapped binaries like gum scripts/install.sh 118-221

**Sources:**

- src/flows/doctor-health-contributions.ts 164-170
- src/cli/update-cli/update-command.ts 97-116
- src/commands/doctor/shared/codex-route-warnings.ts 35-37
- scripts/install.sh 118-221
