Permission surface

permission-surface

Scan first. Do not install, import, source, execute, or run package-manager hooks from the target artifact as part of the scan.

Workflow

1. Identify a local, unpacked directory containing the artifact. If only an install command or remote URL is available, ask for or create a non-executed source checkout/download using a human-approved method; do not use the artifact's installer to obtain it.

2. From this skill's repository, run:

   node src/scan.mjs /path/to/unpacked-artifact
   

   Use --format json when machine-readable output is useful.

3. Present the complete SURFACE REPORT to the human before any install command. Call out high-severity findings, network domains, lifecycle hooks, mutable references, outside-repository writes, and every observed capability that was not declared.

4. State the disclaimer exactly: This is a STATIC heuristic scan, not a security audit. Findings may include false positives and miss real risks.

5. Do not label the artifact safe or malicious. Explain that severity prioritizes review, then wait for the human's explicit installation decision.

6. Only after explicit approval may the separate installation workflow proceed, for example npx skills add ....

Report interpretation

• QUIET means no v1 heuristic matched, not that the artifact is safe.
• A declaration gives context but does not erase a finding.
• A mutable fetch can deliver different bytes later even if this repository does not change.
• A secret-looking match may be sample data; evidence is redacted in the report.
• Inspect the cited file and line in context and respect the scanned project's license.

The scanner reads files only. It skips .git, node_modules, binary-looking files, and symlinks, and it does not execute target content or make network requests.