ironheights 0.1.1 → 0.1.5

package/README.md

@@ -60,12 +60,32 @@ Verdict: review
 Absence of findings is not proof of safety.
 ```
 
-Exit codes are `0` for no findings, `1` for review, `2` for block, `64` for a usage or config error, and `70` for an internal error. `--fail-on low|medium|high|critical` returns `0` when every finding is below that severity.
+| Exit | Meaning                                                                                        |
+| ---- | ---------------------------------------------------------------------------------------------- |
+| 0    | No findings                                                                                    |
+| 1    | Review                                                                                         |
+| 2    | Block                                                                                          |
+| 3    | Incomplete. A file was skipped, and the files that were scanned did not reach review or block. |
+| 64   | Usage or config error                                                                          |
+| 70   | Internal error                                                                                 |
+
+`--fail-on low|medium|high|critical` returns `0` when every finding is below that severity and no file was skipped. A skipped file still returns `3` unless you pass `--allow-skipped`. That flag keeps the skipped-file warning and returns the finding verdict (`0`, `1`, or `2`) instead.
+
+A scan that skipped a file looks like this:
+
+```text
+padded
+  warning: skipped payload.md (file exceeds 1048576 bytes)
+  Scan incomplete: 1 file was not scanned.
+
+Verdict: incomplete
+Absence of findings is not proof of safety.
+```
 
 ## Commands
 
 ```text
-ironheights scan <path> [--all] [--json] [--sarif <file>] [--md <file>] [--fail-on <severity>] [--config <file>] [--no-color] [--quiet]
+ironheights scan <path> [--all] [--json] [--sarif <file>] [--md <file>] [--fail-on <severity>] [--config <file>] [--allow-skipped] [--no-color] [--quiet]
 ironheights baseline create|update|show
 ironheights verify
 ironheights quarantine <skill>
@@ -96,7 +116,7 @@ Ironheights reads `ironheights.config.json` from the current directory, then `~/
 }
 ```
 
-An allowlist entry matches that host and its subdomains. The built-in list includes `example.com`, `example.org`, `example.net`, `localhost`, GitHub, npm, PyPI, and `openclaw.ai`.
+An allowlist entry matches that host and its subdomains. The built-in list includes `example.com`, `example.org`, `example.net`, `localhost`, the loopback addresses `127.0.0.1` and `::1`, GitHub, npm, PyPI, and `openclaw.ai`.
 
 ## JSON output
 
@@ -105,16 +125,17 @@ An allowlist entry matches that host and its subdomains. The built-in list inclu
 ```json
 {
   "schemaVersion": 1,
-  "tool": { "name": "ironheights", "version": "0.1.1" },
+  "tool": { "name": "ironheights", "version": "0.1.5" },
   "scannedAt": "2026-10-09T00:00:00.000Z",
   "verdict": "no-findings",
+  "skippedFileCount": 0,
   "skills": []
 }
 ```
 
-Each skill has `skillName`, `root`, `filesScanned`, `filesSkipped`, `findings`, `score`, and `verdict`. A finding has `ruleId`, `severity`, `confidence`, `file`, optional `line` and `column`, `evidence`, `message`, and `remediation`. `--sarif` writes SARIF 2.1.0.
+Each skill has `skillName`, `root`, `filesScanned`, `filesSkipped`, `skippedFileCount`, `findings`, `score`, and `verdict`. `skippedFileCount` is the number of files the scan did not read. `filesSkipped` lists each path and the reason. A finding has `ruleId`, `severity`, `confidence`, `file`, optional `line` and `column`, `evidence`, `message`, and `remediation`. `--sarif` writes SARIF 2.1.0. The run `properties.skippedFileCount` is the same total, and `tool.driver.informationUri` is `https://github.com/Frank-Masciopinto/ironheights`.
 
-Scoring is critical 100, high 40, medium 15, low 5, info 0. The verdict is `block` when any finding is critical or the score is at least 80. It is `review` when any finding is high or medium, or the score is at least 15. Otherwise it is `no-findings`.
+Scoring is critical 100, high 40, medium 15, low 5, info 0. The verdict is `block` when any finding is critical or the score is at least 80. It is `review` when any finding is high or medium, or the score is at least 15. It is `incomplete` when files were skipped and the score would otherwise be `no-findings`. Otherwise it is `no-findings`.
 
 ## Rules
 
@@ -133,16 +154,23 @@ Verified against the OpenClaw docs for the 2026.9.3 line:
 | Personal agent skills | `~/.agents/skills`                                     |
 | Managed skills        | `~/.openclaw/skills`                                   |
 | Workshop skills       | `~/.openclaw/agents/<agent>/agent/workshop-skills`     |
+| Bundled skills        | `<openclaw package>/skills`                            |
+| Custodian skills      | `<openclaw package>/custodian-skills`                  |
+| Plugin skills         | real paths linked from `~/.openclaw/plugin-skills`     |
 | Extra directories     | `skills.load.extraDirs` in `~/.openclaw/openclaw.json` |
 
 The default workspace is `~/.openclaw/workspace`. Config is `$OPENCLAW_CONFIG_PATH` or `~/.openclaw/openclaw.json`. State moves when `OPENCLAW_STATE_DIR` is set.
 
 Watched agent files default to `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, `TOOLS.md`, `BOOTSTRAP.md`, `MEMORY.md`, the `memory/` directory, `openclaw.json`, `credentials/`, and `.env` under the OpenClaw state directory. Change the list with `agentFiles`.
 
-`TODO(verify)`: bundled skills live inside the OpenClaw install and are not scanned unless you add that directory to `skillDirs`. Plugin skills were observed at `~/.openclaw/plugin-skills` on one machine; the docs name them as a load source without one portable path. `doctor` marks that directory as unverified.
+Bundled skills are the `skills/` directory in the OpenClaw package. Ironheights finds that package from `OPENCLAW_BUNDLED_SKILLS_DIR`, from the `~/.openclaw/bin/openclaw` wrapper, from `~/.openclaw/tools/node-v*/lib/node_modules/openclaw`, or from the usual global `node_modules/openclaw` locations. Custodian skills are the sibling `custodian-skills/` directory. Plugin skills are the directories linked from `~/.openclaw/plugin-skills`. `doctor` says when the bundled directory was not found.
 
 `SKILL.md` needs YAML frontmatter with `name` and `description`. Optional fields include `metadata.openclaw`, `homepage`, `user-invocable`, `disable-model-invocation`, and the `command-dispatch` keys.
 
+`metadata.ironheights.allowDomains` is a list of hosts that this skill is allowed to contact. `IH-NET-001` skips those hosts and their subdomains for that skill only. Another skill that calls the same host still reports. The bundled OpenClaw skills do not declare their hosts, so `scan --all` on a stock install still reports their API hosts.
+
+A download, install, or fetch instruction is a contact, and so is a paste site or a file-drop host. A schema link, or an official API host mentioned in prose, is not.
+
 ## Integrity
 
 `baseline create` writes `~/.ironheights/baseline.json` with mode `0600`. The file stores a sha256, size, and mode for each path, plus a `treeHash` of the sorted content hashes. `verify` reports added, modified, removed, and mode-changed files.