Permission Manifest Guard

Inspects an OpenClaw skill directory before install or execution, translates declared and observed requirements into a human-readable permission manifest, an...

Security Scan

The skill's code, docs, and runtime instructions are consistent with its stated purpose of statically analysing a skill directory and producing a permission manifest; nothing requested or installed is disproportionate or unrelated to that purpose.

Purpose & Capability

Name/description (permission manifest / static analysis) match the implementation: modules for discovery, extraction, classification, policy, and rendering exist (src/discovery.ts, src/extract.ts, src/classify.ts, src/policy.ts, src/render.ts). The declared capability in SKILL.md is read_filesystem and the code reads files from a supplied skill directory. No unrelated credentials or platform services are requested.

Instruction Scope

SKILL.md and README clearly limit the tool to static analysis of a supplied directory and describe expected outputs (markdown to stdout, JSON written to the target directory by the CLI). The CLI (src/cli.ts) does write permission-manifest.json into the inspected directory as a documented side effect. The code only scans files present in the target directory and does not perform network calls or attempt to access external credentials. Note: the repository includes a CLAUDE.md governance document that instructs running an external 'saturnday' tool — that is documentation only and not invoked by the code, but reviewers should be aware of it.

Install Mechanism

Registry metadata lists no install spec (instruction-only), which is low-risk. However, full source files are included in the package (TypeScript sources, package.json, package-lock.json). There is no automated install-from-URL or arbitrary archive extraction. The package.json declares ordinary npm deps (js-yaml) and devDependencies; there is no build/install script that fetches remote code beyond normal npm behavior. Slight mismatch: 'instruction-only' in registry vs presence of code files is benign but worth noting.

Credentials

The skill does not require environment variables or credentials and does not declare a primary credential. The code reads process.env occurrences in target code for detection purposes (extractors look for env-var usage) but does not itself read or transmit host credentials. It classifies env var names and flags likely secrets for the manifest; that is appropriate for its purpose.

Persistence & Privilege

The skill does not request permanent or elevated platform privileges (always:false). The CLI writes a permission-manifest.json file into the inspected skill directory (documented side effect). This write is proportionate to the stated behavior but you should be aware the tool modifies the inspected directory when run via the CLI. The code explicitly ignores symlinks during discovery (shouldIgnoreEntry) — this is a design choice, not a hidden privilege escalation.

Assessment

This skill appears coherent and implements a static permission manifest generator. Before running it: 1) Understand that its analysis is static only — it cannot see runtime behavior or transitive dependency actions; treat the manifest as an aid, not a proof. 2) The CLI will write permission-manifest.json into the inspected directory — run it on a copy or in a sandbox if you don't want repository files modified. 3) Inspect package.json dependencies (js-yaml) and run standard checks (npm install in an isolated environment, npm audit) if you plan to build/run locally. 4) Note the repository includes a CLAUDE.md that mentions an external 'saturnday' governance tool — that's documentation and not executed by the tool, but verify any external governance workflow separately. 5) If you need runtime/supply-chain guarantees (transitive dependency behavior, network reachability), use dynamic or dependency-specific scanners in addition to this tool.

When to invoke

Use this skill when you need to understand what permissions a skill requires before granting trust. Invoke it when:

• Reviewing a new skill before install — a skill has been downloaded or proposed and you need to know what it accesses before allowing execution.
• Checking skill permissions — you want a summary of every permission-relevant signal (binaries, network, env vars, file paths, shell commands, config files, package managers, risky capabilities).
• Generating a permission manifest — you need a human-readable markdown report and a machine-parseable JSON manifest for audit or policy decisions.
• Deciding whether to sandbox or reject a skill — the skill's observed behaviour may exceed its declared capabilities and you need a scored recommendation.
• Auditing a skill's declared vs observed behaviour — you want to compare what SKILL.md claims against what the source code actually does.

If the task does not involve evaluating skill trust, permissions, or install safety, this skill is not the right tool.

How to call — CLI

Run the skill from the command line, passing the skill directory as the sole argument:

npx permission-manifest-guard /path/to/skill

Stdout: The markdown permission manifest (human-readable report). Pipe or redirect as needed.

Stderr: Diagnostic warnings from analysis stages, plus the path to the written JSON file.

Side effect: Writes permission-manifest.json into the skill directory. This file contains the structured manifest for machine consumption.

Exit code: 0 on success, 1 on invalid arguments or analysis failure.

How to call — programmatic

Import analyzeSkill and call it with the skill directory path:

import { analyzeSkill } from 'permission-manifest-guard';

const result = await analyzeSkill('/path/to/skill');

The returned AnalysisResult has three fields:

Field	Type	Description
markdownManifest	string	Complete markdown permission report.
jsonManifest	object	Structured manifest matching the markdown data.
diagnostics	DiagnosticWarning[]	Warnings from discovery, extraction, or classification stages. Each entry has file, stage, message, and error fields.

What to do with the output

The analysis produces a disposition recommendation based on how well the skill's declared metadata matches its observed source-code behaviour. Act on the recommendation as follows:

• allow — Declared capabilities match observed behaviour. No undeclared access detected. Install the skill normally.
• review — Minor mismatches found (e.g. an undeclared env var or a low-severity capability gap). Inspect the mismatches in the manifest before proceeding. A human or policy check should confirm intent.
• sandbox — Significant undeclared capabilities detected. Install only within an isolated execution environment with restricted filesystem, network, and process access.
• reject — Severe mismatches or dangerous undeclared capabilities. Do not install. Flag the skill for further investigation or removal from the registry.

The markdown manifest is the artifact for humans — include it in review threads, audit logs, or approval workflows. The JSON manifest is for automated pipelines — feed it to policy engines, dashboards, or gating checks.

If diagnostics is non-empty, some files could not be fully analysed. Treat a skill with analysis warnings more cautiously — incomplete analysis means the true permission surface may be larger than reported.

Limitations

• Static analysis only. The skill inspects source code and metadata files. It does not execute the skill or trace runtime behaviour. Dynamically constructed commands, lazy imports, or runtime code generation will not be detected.
• No transitive dependency scanning. Only files within the skill directory are analysed. If the skill depends on external packages that perform privileged operations, those will not appear in the manifest.
• Heuristic extraction. Binary, domain, env-var, and shell-command extraction uses pattern matching. Unusual code patterns may produce false positives or false negatives.
• Single-directory scope. The tool analyses one skill directory per invocation. Multi-skill repositories require separate runs.