Authensor

SafeClaw Doctor: Self-Diagnosing Configuration Issues

Authensor Team · 2026-02-13

SafeClaw Doctor: Self-Diagnosing Configuration Issues

Configuration is the Achilles' heel of security tools. A firewall with a typo in its rules is worse than no firewall at all — it gives you false confidence while providing no protection. SafeClaw's doctor command exists to make sure your configuration is correct, complete, and doing what you think it's doing.

Why We Built It

During our beta, the number one support request wasn't "SafeClaw doesn't work." It was "SafeClaw isn't doing what I expected." Users would write a policy, test it casually, deploy it, and then discover weeks later that a subtle misconfiguration had left a gap in their protection.

Common issues we saw:

These are exactly the kind of issues that humans are bad at spotting in configuration files and that machines are great at detecting automatically.

What Doctor Checks

Running safeclaw doctor performs a comprehensive analysis of your configuration:

Syntax Validation — Is your configuration file valid YAML/JSON? Are all required fields present? Are values the correct types? This catches typos and structural errors. Semantic Validation — Do your policy rules reference valid action categories? Do your profiles reference existing policies? Are your cron expressions valid? This catches logical errors that are syntactically correct but meaningfully wrong. Conflict Detection — Are any policy rules shadowed by earlier rules? Are there profiles with conflicting workspace boundaries? Do inherited profiles override critical settings unintentionally? Doctor reports conflicts with specific line numbers and explanations. Coverage Analysis — Are there action categories with no matching policy rules? This indicates gaps in your protection. Doctor reports uncovered categories and suggests rules to fill them. Performance Analysis — Are any policy rules unnecessarily expensive to evaluate? Complex regex patterns, deeply nested glob expressions, or large exclusion lists can slow down the classifier. Doctor flags these with optimization suggestions. Environment Checks — Is the SafeClaw daemon running? Are required directories writable? Is the configured port available? Are there version mismatches between the CLI and daemon? This catches operational issues.

The Output

Doctor produces a structured report organized by severity:

``

$ safeclaw doctor

[PASS] Configuration syntax is valid

[PASS] All profiles resolve correctly

[WARN] Policy rule on line 23 is shadowed by rule on line 15

[WARN] No policy rule covers 'package_install' actions

[FAIL] Workspace boundary ~/projects does not exist

[FAIL] Port 3827 is in use by another process

2 errors, 2 warnings, 2 passed

`

Each finding includes a description of the issue, why it matters, and a suggested fix. For warnings and errors, we include the specific configuration lines involved so you can navigate directly to the problem.

Automated Doctor Runs

You can integrate safeclaw doctor into your CI pipeline to catch configuration issues before they reach production. The command returns a non-zero exit code when errors are found, making it compatible with standard CI/CD tooling.

We also recommend running doctor after any configuration change. Add it as a git pre-commit hook for your SafeClaw configuration file, and you'll catch issues before they're committed.

Interactive Fix Mode

For common issues, doctor can fix problems automatically with safeclaw doctor --fix`. It will correct shadowed rules, add missing action categories, and fix common glob pattern mistakes. Fixes are previewed before application, and the original configuration is backed up.

Full documentation on doctor's checks and configuration is on our docs site. The implementation is on GitHub.

A safety tool is only as good as its configuration. Doctor makes sure your configuration is as good as your intentions.