yaojingang
79 lines
4.4 KiB
Markdown
79 lines
4.4 KiB
Markdown
# Trust Security Method
|
|
|
|
Trust checks make skills safer to install and review, especially when they include scripts or are distributed to a team.
|
|
|
|
## When To Run
|
|
|
|
Run the trust report when:
|
|
|
|
- the skill contains scripts
|
|
- the skill will be shared with a team
|
|
- the package may be installed from a registry or plugin
|
|
- the skill reads external files, uses network access, or shells out
|
|
- the maturity tier is library or governed
|
|
|
|
## V0 Checks
|
|
|
|
- obvious secret patterns
|
|
- script help surface and interactive prompts
|
|
- execution-level `--help` smoke checks
|
|
- dependency pinning
|
|
- runtime trust metadata
|
|
- network-capable scripts
|
|
- bounded host policy for network-capable scripts
|
|
- reviewer-approved permission policy for high-permission capabilities
|
|
- packaged-target runtime permission probes for adapter contracts and metadata fallback limits
|
|
- source-contract integrity digest
|
|
|
|
## Script Interface Rule
|
|
|
|
Every Python file under `scripts/` is reviewed as part of the package trust surface.
|
|
|
|
- CLI scripts should use `argparse` so reviewers and installers can run `python3 scripts/name.py --help` before execution.
|
|
- The trust report executes `python3 scripts/name.py --help` for CLI scripts with `argparse`, with a short timeout, and records pass/fail evidence.
|
|
- Import-only modules should declare `SCRIPT_INTERFACE = "internal-module"` near the top of the file.
|
|
- Internal modules should also declare `SCRIPT_INTERFACE_REASON` with a short explanation of which CLI or renderer imports them.
|
|
- The trust report keeps internal modules in the script inventory, but excludes them from CLI help-surface warnings.
|
|
- A Python file without an explicit internal-module declaration is treated as a CLI script by default.
|
|
- CLI scripts without `argparse` are not smoke-executed; they remain visible as help-surface warnings.
|
|
|
|
## Network Policy Rule
|
|
|
|
Network-capable scripts must be bounded by a machine-readable policy before team distribution.
|
|
|
|
- Put the policy in `security/network_policy.json`.
|
|
- Add one entry per network-capable script under `scripts`.
|
|
- Declare `allowed_hosts`, `allowed_path_prefixes`, purpose, timeout, auth mode, and custom-host behavior.
|
|
- Default to HTTPS-only and deny custom hosts unless a CLI flag or environment variable makes the override explicit.
|
|
- The trust report compares HTTPS URL literals in each script with `allowed_hosts`; missing or mismatched entries remain reviewer-visible warnings.
|
|
|
|
## Permission Approval Rule
|
|
|
|
High-permission capabilities must be approved before governed release.
|
|
|
|
- Put approvals in `security/permission_policy.json`.
|
|
- Cover each required capability detected by the trust report: `network`, `file_write`, `subprocess`, and `interactive` when present.
|
|
- Each approval must include `decision: approved`, `reviewer`, `scope`, `reason`, `expires_at`, `evidence`, and `target_enforcement`.
|
|
- Review Studio surfaces these checks as the `permission-gates` gate.
|
|
- Missing, invalid, or expired approvals block governed mode. They remain visible warnings in lighter modes.
|
|
|
|
## Runtime Permission Probe Rule
|
|
|
|
Permission approval validates reviewer intent. Runtime permission probes validate the generated target adapters after packaging.
|
|
|
|
- Run `python3 scripts/probe_runtime_permissions.py . --package-dir dist` after `cross_packager.py`.
|
|
- The probe writes `reports/runtime_permission_probes.json` and `reports/runtime_permission_probes.md`.
|
|
- A passing probe requires every target adapter to carry `permission_contract`, `target_permission_contract`, declared capabilities, a native-enforcement boolean, representation notes, and operator notes.
|
|
- If a target has no native enforcement, the probe must mark an explicit metadata fallback and keep residual risk reviewer-visible.
|
|
- Review Studio surfaces this as the `permission-runtime` gate.
|
|
|
|
## Release Rule
|
|
|
|
High-risk secrets or unrestricted remote inline execution block governed release. Warnings are reviewer-visible but do not block v0 unless the release owner decides the target environment requires stricter policy.
|
|
|
|
## Hash Scope
|
|
|
|
`package_sha256` is a stable source-contract digest, not a generated archive digest. It covers the skill entrypoint, metadata, scripts, references, evals, runtime, templates, security notes, Skill IR, and root control files. It deliberately excludes generated `reports/`, packaged `dist/` archives, and raw local telemetry so a report render or local adoption log cannot mutate the trust fingerprint.
|
|
|
|
Use the package verification or registry audit report for the distributable archive checksum.
|