Skip to content
Ironheights

Features

Version 0.3.0 checks how Ironheights sits beside the other security tools on your agent. The 0.2.0 release went beyond scanning: it can fetch and vet a skill before installing it, match skills against a signed advisory feed, sign your baseline, and watch an agent's tool calls. Each feature below says what it does, how to run it, and where it stops.

Quick answerLast updated

What is new in Ironheights 0.3.0?

Version 0.3.0 adds ironheights coexist, which finds other security tools on your machine and reports where they overlap with Ironheights, plus a guard priority setting. The 0.2.0 release added fetch and safe-install, signed baselines, an A to F grade, honest incomplete verdicts and an optional guard plugin that is not a sandbox. Detection is heuristic.

Every command below is in ironheights 0.3.0 on npm. Angle brackets such as <owner>/<slug> are placeholders you fill in. A scan reports what its rules match. No findings is not proof of safety, and none of these features changes that.

New in 0.3.0: next to your other security tools

Most agents that care about security already run something else. Ironheights now looks for it, tells you where the two would collide, and stays out of the way.

New in 0.3.0

Works next to your other security tools

Many OpenClaw setups already run a ClawHub vetting skill, a guard plugin or a scanner such as Cisco's skill-scanner. ironheights coexist looks for them and reports where two tools would get in each other's way, with a fix for each. It reads files only, runs none of the other tools, and changes nothing.
  • It reads your OpenClaw config (plugin and hook entries), plugin manifests, skill and hook folders, known state folders, PATH, and CI or pre-commit files in a project. Each tool it lists shows the file that gave it away.
  • Eleven checks, IH-COEX-001 to IH-COEX-011: two guards on the same tool call, Ironheights in enforce mode blocking another tool, two tools restoring the same files, shared state paths, a config that exempts a security tool by name, and more. Each has a severity and a fix.
  • Text for people, --json for scripts, and --fail-on to exit 1 in CI when a finding reaches a severity.
  • doctor prints a one-line summary, and the guard plugin writes one log line at startup when it sees another tool.

See what runs next to Ironheights

npx ironheights coexist

Fail a CI job on a medium or higher overlap

npx ironheights coexist --json --fail-on medium

Include a project's CI and pre-commit files

npx ironheights coexist --repo <path-to-project>
Where it stops
Detection is heuristic. It reads files and names, so a tool that is not on its list, was renamed, or is only loaded in a running Gateway can be missed, and anyone can copy a name. No findings is not proof that two tools will not interfere.
Coexistence docs (opens in a new tab)
New in 0.3.0

A guard that shares the hook

OpenClaw runs before_tool_call handlers from the highest priority down, and a block ends the chain. The Ironheights guard now runs at priority 80, and one setting changes it. In monitor mode, the default, it never blocks, so another guard can own blocking.
  • Set plugins.entries.ironheights-guard.config.priority to an integer from -1000 to 1000. Higher runs first, and OpenClaw's own default is 0.
  • The guard returns only block and blockReason. It never rewrites parameters and never asks for approval, so it cannot collide with another plugin's rewrite or prompt.
  • Every block reason starts with ironheights:, so you can tell whose block you are reading.
  • Its files all live under ~/.ironheights, apart from other tools' folders. coexist flags the case where IRONHEIGHTS_HOME points at a shared folder.
  • At startup the plugin writes one log line when it sees other security tools. It has a three-second limit and cannot delay OpenClaw.

Plugin config with a priority

{ "plugins": { "entries": { "ironheights-guard": { "enabled": true, "config": { "mode": "monitor", "priority": 80 } } } } }

Check mode, policy and log

npx ironheights guard status
Where it stops
Priority sets the order, not who is right. When two guards enforce, the higher one blocks first and the other never sees that call, so its log is missing it. The hook still runs inside the agent and is not a sandbox. Hook order follows OpenClaw's plugin docs as checked on 11 October 2026 and can change.
Guard docs and threat model (opens in a new tab)
New in 0.3.0

Security tools are not trusted by name

Security skills quote attack strings and list credential paths because that is their job, so a scanner flags them. When a scanned skill's folder or SKILL.md name matches a tool Ironheights knows, scan adds a note and lowers confidence by one step on its Markdown injection and credential findings. It never hides a finding, and the verdict, grade and exit code do not change.
  • The note reads: name match only, not verified. Anyone can copy a name.
  • Only injection and credential findings in Markdown files are affected. Scripts, config, binaries, network, obfuscation, persistence and exec findings are untouched.
  • Nothing is allowlisted. If you trust one copy, review it, then baseline it, or add a suppression with a written reason for that file and line.
  • coexist reports IH-COEX-010 when your own config exempts a path that carries the name of a security tool.

Scan a security skill and read the note

npx ironheights scan <path-to-skill>
Where it stops
A name match proves nothing about the files. The note helps you read findings. It is not a clearance, and a malicious skill that borrows a familiar name gets the same verdict as any other.
Coexistence docs (opens in a new tab)

New in 0.2.0: protection beyond scanning

Checks before you install a skill, while your agent runs, and after something changes.

New in 0.2.0

Fetch and safe-install

Until now you had to download a skill, then point the scanner at it. Now one command does both. fetch downloads a ClawHub skill into a staging folder without running anything and scans it. safe-install does the same and copies the skill into your skills folder only when the verdict is no-findings.
  • Nothing that is downloaded is executed. Files are written readable only by you (mode 0600) and archives are never extracted.
  • block and incomplete verdicts are never installed. A review verdict installs only if you add --accept-review.
  • If a copy of the skill is already installed it is backed up first and restored if the new copy fails.
  • The download goes to clawhub.ai over HTTPS, redirects are refused, and each file's size and sha256 must match what ClawHub lists. The CLI prints every URL before it asks.

Scan without installing

npx ironheights fetch <owner>/<slug>

Install only if the scan is clean

npx ironheights safe-install <owner>/<slug>

Pin a version and a folder

npx ironheights safe-install <owner>/<slug>@<version> --dir ~/.openclaw/workspace/skills
Where it stops
A clean verdict means no rule matched, not that the skill is safe. This is one of the few commands that uses the network, and only when you run it.
Fetch and safe-install docs (opens in a new tab)
New in 0.2.0

Signed advisory feed support

Pattern rules find risky text. An advisory finds a skill that someone has already reported, even when its text looks harmless. The 0.2.0 release can download a signed advisory feed, verify its signature against a key built into the CLI, and report a match as IH-ADV-001.
  • The feed is checked with an Ed25519 signature. A bad signature is rejected and never cached.
  • scan and fetch compare the skill name, file hashes and indicator hosts with the cached feed, offline. A match is critical, so it blocks safe-install.
  • ironheights advisories update is the only command that downloads the feed. There is no telemetry and no client id.
  • The CLI never invents severity. The status shown is the one the source stated.

Download and verify the feed

npx ironheights advisories update

Show what is cached

npx ironheights advisories show

Scan; a match is reported as IH-ADV-001

npx ironheights scan <path>
Where it stops
The feed is not published yet. Until it is, advisories update has nothing to download and scans report nothing from the feed. A skill missing from a feed is not evidence that it is harmless.
Advisory feed docs (opens in a new tab)
New in 0.2.0

Signed baselines

A baseline is a saved list of hashes for your skills and agent files. If an attacker can edit that list as well as the files, verify has nothing to compare against. Now you can sign the baseline with a key file you keep somewhere safer, and verify checks the signature.
  • Sign with an HMAC-SHA256 or an Ed25519 key file. Ironheights does not create or store the key for you, and on macOS and Linux it refuses a key file that other users can read.
  • A baseline whose signature does not match is reported as a tampered baseline: a critical IH-INT-001 finding and exit code 2.
  • A baseline rewritten so its hashes still agree with each other still fails the signature check.

Make a key file (run in a clone of the repository)

node scripts/generate-baseline-key.mjs --alg ed25519 --out ~/.ironheights/baseline.key

Create a signed baseline

npx ironheights baseline create --key ~/.ironheights/baseline.key

Verify it, signature included

npx ironheights verify --key ~/.ironheights/baseline.key
Where it stops
An attacker who can write your home directory and also has the key can sign a new baseline. Keep the key file private, and a copy of it off the machine if you can.
Baseline signing docs (opens in a new tab)
New in 0.2.0

Guard plugin for agent tool calls

Scanning reads files. The guard watches what the agent is about to do. It is an OpenClaw plugin that checks each tool call against four risky behaviors and writes a redacted line to a local log. It starts in monitor mode: it logs and does not block anything. Enforce mode is opt-in.
  • Credential reads: SSH, cloud and wallet folders, private keys, .env files, and OpenClaw credentials.
  • Download-and-execute: curl or wget piped into a shell, and a downloaded file that is then run.
  • Network: a request to a host that is not on your allowlist, or to a paste site, file-drop host, tunnel or raw IP address.
  • Writes to the agent's identity and memory files, such as AGENTS.md, SOUL.md and MEMORY.md, and to skill folders.
  • In enforce mode a matching call is blocked until your policy file has an allow entry with a reason.

Enable the plugin in OpenClaw

openclaw plugins install --link /path/to/ironheights --force
openclaw plugins enable ironheights-guard

Check mode, policy and log

npx ironheights guard status

Read the recent log

npx ironheights guard log
Where it stops
The guard is not a sandbox. It runs inside the OpenClaw process, so a compromised skill that can edit your OpenClaw config or the policy file can switch it off. It sees only the tool name and parameters OpenClaw passes in. A quiet log is not proof that nothing happened.
Guard docs and threat model (opens in a new tab)
New in 0.2.0

A to F trust grade

Every scan now prints a grade next to the verdict: a score from 0 to 100 turned into a letter. It is a summary of the same risk points the rules already add up, so it never says more than the findings do. The grade appears in JSON, in a one-file HTML report, and as a README badge line that does not call any badge service.
  • A is 90 to 100, B 80 to 89, C 70 to 79, D 60 to 69, and F 0 to 59.
  • The grade uses the worst skill in the scan, after suppressions.
  • scan --html writes one self-contained report with no scripts and a strict content security policy.
  • Every grade is printed with the line “Absence of findings is not proof of safety.”

Scan and read the grade

npx ironheights scan <path>

Write a shareable HTML report

npx ironheights scan <path> --html report.html
Where it stops
An A means the rules found little to add up. It does not mean the skill is safe. A scan that skipped anything is graded incomplete, with no number.
Grade and report docs (opens in a new tab)
New in 0.2.0

Honest incomplete verdicts

A padded file or a folder the scanner did not enter should never read as a clean result. When a file is skipped for size, or .git or node_modules is not entered, the report names each one, the verdict is incomplete and the exit code is 3, unless the scanned files already reached review or block.
  • dist/ is scanned like any other folder, so a pipe-to-shell line there is a finding.
  • .git and node_modules are listed in the text report, in JSON skippedDirectories and in SARIF.
  • --allow-skipped keeps the warning and returns the finding verdict; the grade stays incomplete.
  • ignoreDirs in config, with a written reason, acknowledges a folder so it no longer makes the scan incomplete.

A scan that skipped something exits 3

npx ironheights scan <path>; echo $?

Accept the skipped folders, with the warning kept

npx ironheights scan <path> --allow-skipped
Where it stops
Incomplete means part of the skill was not checked at all. --allow-skipped and ignoreDirs let you accept that. They do not scan what was skipped.
Scan limits docs (opens in a new tab)
Fixed in 0.2.0

Piped JSON that stays whole

Earlier versions could cut a long report off at 64 KiB when you piped it, which left broken JSON. The 0.2.0 release waits until the pipe has taken the whole report before it exits. The exit code is unchanged.
  • Applies to scan --json, scan --format html, and every other command that writes to stdout.
  • A report written to a file with --sarif or --html was already complete.

Pipe a full report

npx ironheights scan --all --json | jq '.verdict'
Where it stops
This is a bug fix, not a new detection. It does not change what a scan finds.
Changelog (opens in a new tab)

Also in 0.2.0

Smaller additions that make the scanner easier to fit into CI, other agents and your own config.

New in 0.2.0

OpenClaw config audit

audit-config reads your local OpenClaw config and reports nine kinds of risky setting: an exposed Gateway, missing auth, open DMs or groups, literal secrets, loose file permissions, broad tool power, extra skill folders, and a disabled sandbox.
  • Offline and read-only. Secret values are replaced with <redacted>.
  • Rules IH-CFG-001 to IH-CFG-009, output as text, JSON or SARIF.
  • It does not replace openclaw security audit, which also probes a running Gateway.

Audit your config

npx ironheights audit-config
npx ironheights audit-config --json --fail-on high
Where it stops
It reads the file, not the running system. Settings that come from environment variables are not seen.
audit-config docs (opens in a new tab)
New in 0.2.0

MCP configuration rules

scan now reads MCP configuration files and reports a server started from a downloaded script or an unpinned npx package, a literal secret in a server's environment, and a filesystem server pointed at a whole disk or home folder.
  • Rules IH-MCP-001, IH-MCP-002 and IH-MCP-003.
  • Works on Claude Code, Codex and Cursor skill folders too: point scan at the folder.

Scan a folder with an MCP config

npx ironheights scan <path-to-folder>
Where it stops
CLI only: the in-browser scanner does not run these rules. A pinned package can still be malicious.
Other agents and MCP docs (opens in a new tab)
New in 0.2.0

Only what is new

scan --since-baseline compares the scan with a saved baseline or a previous JSON result and reports only findings that are new. The ones left out are counted and listed, and the exit code follows the new findings.
  • Works with an integrity baseline or a previous --json result.
  • Omitted findings still count toward the grade.

Report only new findings

npx ironheights scan <path> --since-baseline previous.json
Where it stops
A finding you already accepted is hidden from the list, not made safe.
Changelog (opens in a new tab)
New in 0.2.0

Scan a piece of text

scan --stdin and scan --text run the same content rules on one piece of text, labelled as a limited text scan. The text is never executed.
  • --stdin reads a pipe and returns a usage error on a terminal.
  • Text scans are never sent to a model.

Scan pasted text

cat <email.txt> | npx ironheights scan --stdin
npx ironheights scan --text "<text to check>"
Where it stops
A text scan has no skill folder, so it cannot check files, hashes or the baseline.
Changelog (opens in a new tab)
New in 0.2.0

Suppressions that need a reason

An inline ironheights-ignore comment or a config suppression must carry a written reason of at least eight characters. Suppressed findings are counted and listed, and critical and integrity findings stay visible unless you say otherwise.
  • A marker with no usable reason is listed and does not hide the finding.
  • A comment applies to its own line and the next.

An inline suppression

# ironheights-ignore IH-CRED-001 reason="reviewed local demo"
Where it stops
A suppression records your decision. It does not make the line safe.
Changelog (opens in a new tab)
New in 0.2.0

CI action, pre-commit hook and Windows

A composite GitHub Action runs a pinned npm release of the scanner. A pre-commit hook scans a tree when a SKILL.md changes. Windows CI now builds and tests the CLI on Node.js 20.0.0 and 24, and path handling accepts ~\ and %USERPROFILE%.
  • The action needs an exact version, such as 0.3.0, and takes no token for scanning.
  • Exit code 3 still means the scan was incomplete.

GitHub Actions step

- uses: Frank-Masciopinto/ironheights@v0.3.0
  with:
    version: '0.3.0'
    path: .
    fail-on: high
Where it stops
Windows support is new in 0.2.0 and is checked in CI, not yet as widely used as macOS and Linux.
CI docs (opens in a new tab)
New in 0.2.0

Optional model second opinion

scan --llm and review send a capped, secret-scrubbed copy of the skill to a model server you choose and add advisory notes as IH-LLM-001. It is off unless you ask. The default is a loopback Ollama-compatible server.
  • A non-local server needs --llm-consent and an API key, and the exact request is printed before it is sent. --dry-run prints it without sending.
  • Notes score zero. They never change the verdict, the grade or the exit code.

See what would be sent

npx ironheights review <path> --dry-run
Where it stops
Models can be wrong, and the scrub can miss a secret. A silent model is not a clearance.
Model review docs (opens in a new tab)

What none of this is

  • The guard is not a sandbox, an antivirus, or a process outside the agent. A compromised skill that can edit your OpenClaw config can turn it off.
  • A grade, a signature or a quiet log is not a safety rating. Absence of findings is not proof of safety.
  • The advisory feed is not published yet, so a scan reports nothing from it today. When a feed is live, a skill missing from it is still not evidence that the skill is harmless.
  • Detecting other security tools is heuristic. It reads files and names, can miss a renamed or unlisted tool, and cannot tell whether a plugin is loaded in a running Gateway. A name can be copied, so Ironheights never trusts a tool by name.
  • The in-browser scanner runs the content rules only. MCP, advisory, config audit, guard and coexistence checks need the CLI.
Read the docs Read every limitation