Back to skill

Security audit

contract-doc-sync

Security checks for vulnerabilities and agentic risk

Overview

The skill is a plausible documentation sync helper, but it can run a project-provided script and has inconsistent access boundaries that users should review before installing.

Install only if you are comfortable with a doc-sync skill that reads repository code and can edit documentation. Before use, disable or remove project-local md-sections precedence, require approval before L3/cloud semantic review, and enforce the narrower docs/modules, docs/architecture, and docs/conventions write whitelist.

Vulnerability Patterns
  • Unauthorized Access and Privilege EscalationObtains permissions beyond the task's legitimate needs
  • Tool Hijacking and SpoofingModifies or replaces tools so legitimate-looking calls execute attacker logic
  • Skill Instruction HijackingAlters the agent's session goals or safety constraints when the skill loads
  • Agent Memory PoisoningWrites attacker-controlled rules into memory that affect later sessions
  • Remote Payload Retrieval and ExecutionFetches external code whose behavior can change after review
Findings (2)

T07 · Tool Hijacking and Spoofing

Error
Location
SKILL.md:41
Finding

Repository-Controlled Markdown Parser Can Execute Arbitrary Code

Content
View full analysis

Vulnerability Details

File Location: SKILL.md:41, SKILL.md:155, references/environment-probing.md:74, references/environment-probing.md:607-613, references/sync-procedures.md:6, and references/verification-dimensions.md:7
Vulnerability Type: Untrusted local tool selection and execution
Risk Level: High

Vulnerable Code and Instructions

The security-relevant instruction at SKILL.md:41, translated into English, is:

markdown
`$MD_SECTIONS` is dynamically resolved by Phase 0 Step 3. The project-local
`scripts/md-sections.sh` is preferred, followed by
`$SKILL_DIR/scripts/md-sections.sh`; grep is used only if neither is available.

The executable detection logic at references/environment-probing.md:607-613 is:

bash
if [ -x "scripts/md-sections.sh" ]; then
  echo "Project version: scripts/md-sections.sh"
elif [ -x "$HOME/.config/opencode/skills/contract-doc-sync/scripts/md-sections.sh" ]; then
  echo "Built-in Skill version"
else
  echo "No available version; falling back to grep"
fi

The security-relevant convention at references/sync-procedures.md:6, translated into English, is:

markdown
Every reference to `scripts/md-sections.sh` in this file must be replaced
with the detected `$MD_SECTIONS` path, with the project version preferred
over the built-in Skill version.

Technical Analysis

The target repository is untrusted input to the Skill. Nevertheless, the Skill explicitly gives an executable supplied by that repository precedence over the parser shipped in the audited Skill package.

The only demonstrated eligibility check is whether scripts/md-sections.sh exists and has its executable bit set. This does not verify:

  • Whether the script is the expected Markdown parser.
  • Whether it has been reviewed or approved by the user.
  • Whether it is a symlink to a file outside the repository.
  • Whether its content or cryptographic hash matche ...[truncated 2358 chars]
Remediation
View remediation

Remediation Suggestions

  1. Always use the immutable parser shipped under $SKILL_DIR by default.
  2. Do not execute repository-provided scripts merely because they have an expected filename and executable bit.
  3. If project-specific parsers are necessary:
    • Display the canonical resolved path.
    • Inspect the complete script before execution.
    • Require explicit user approval.
    • Reject symlinks and paths outside the repository.
    • Verify ownership, permissions, and an approved cryptographic hash.
  4. Resolve paths canonically and ensure the selected executable remains within an approved trusted directory.
  5. Prefer implementing Markdown parsing in trusted Skill code rather than invoking a shell script.
  6. Run any explicitly approved repository parser in a sandbox with:
    • Read-only repository access.
    • No credential mounts.
    • No network access.
    • No access to the home directory.
    • A restricted executable allowlist.
  7. Log the selected parser path and hash in the final report.
  8. Update every reference that currently states project-local parser precedence, including SKILL.md, environment-probing.md, sync-procedures.md, and verification-dimensions.md.

T05 · Unauthorized Access and Privilege Escalation

Warning
Location
SKILL.md:55
Finding

Sub-Agent Write Permissions Exceed the Declared Documentation Whitelist

Content
View full analysis

Vulnerability Details

File Location: SKILL.md:55, SKILL.md:278, and references/verification-dimensions.md:63,105,223,373,511,623,743,869,976,1090,1221
Vulnerability Type: Inconsistent access-control and write-scope instructions
Risk Level: Medium

Vulnerable Code and Instructions

The declared whitelist at SKILL.md:55, translated into English, is:

markdown
Writable whitelist:
`docs/modules/*.md`,
`docs/architecture/*.md`,
`docs/conventions/*.md`

The broader permission at SKILL.md:278, translated into English, is:

markdown
May modify: documentation files under `docs/`.

The D1 scope and repeated sub-agent permissions in references/verification-dimensions.md, translated into English, include:

markdown
Inspection scope:
- All `.md` files under `docs/`.

Repair permissions:
- May modify files under `docs/` using precise operations through md-sections.

Equivalent broad write authorization is repeated for multiple dimensions at lines 105, 223, 373, 511, 623, 743, 869, 976, 1090, and 1221.

Technical Analysis

The top-level safety policy promises that modifications are limited to three specific directory patterns. Later orchestration rules and self-contained sub-agent prompts weaken that restriction by authorizing modification of any file beneath docs/.

This discrepancy is security-relevant because sub-agent prompts are operational instructions. A validator may inspect a file outside the whitelist, identify an alleged mismatch, and then rely on its local prompt to modify that file.

Examples of files covered by the broad rule but excluded from the declared whitelist include:

  • docs/README.md
  • docs/templates/*.md
  • docs/guides/*.md
  • Documentation framework or navigation files beneath docs/
  • Any additional project-specific documentation track

No centralized canonical-path authorization check is documented before an Edit operation. ...[truncated 1944 chars]

Remediation
View remediation

Remediation Suggestions

  1. Replace every broad authorization to modify docs/ with the exact whitelist:
    • docs/modules/*.md
    • docs/architecture/*.md
    • docs/conventions/*.md
  2. Add a centralized pre-write authorization function rather than relying only on natural-language instructions.
  3. Before every edit:
    • Resolve the repository root to a canonical path.
    • Resolve the target file to a canonical path.
    • Verify that the resolved target is a regular file.
    • Reject symlinks.
    • Verify that the target matches one of the approved directory and extension patterns.
  4. Treat docs/README.md, template files, navigation files, generated documentation, and unrecognized tracks as read-only unless the user separately approves them.
  5. Include the immutable whitelist in every self-contained sub-agent prompt.
  6. Make a violation of the whitelist a hard failure rather than a warning.
  7. Log every attempted write with its canonical path and whether authorization succeeded.
  8. Add automated tests covering:
    • Allowed files in each whitelisted directory.
    • Files directly under docs/.
    • Unrecognized documentation subdirectories.
    • Symlinks pointing outside the whitelist.
    • Paths containing traversal components.
Vulnerability Patterns
  • Excessive AgencyUnrestricted Tool Access, Autonomous Decision Making, Scope Creep
  • Trigger AbuseOverly Broad Trigger, Shadow Command Trigger, Keyword Baiting Trigger
  • Behavioral ASTexec() Call, eval() Call, Dynamic Import
  • MCP Least PrivilegeUnderdeclared Capability, Wildcard Permission, Missing Permission Declaration
  • MCP Tool PoisoningHidden Instructions, Unicode Deception, Parameter Description Injection
Findings (26)

Tp4

High
Category
MCP Tool Poisoning
Confidence
95% confidence
Finding

The code is consistent with a drift-detection helper, since it parses git diff output, classifies changed files, and maps them to documentation impact targets. However, it does not implement the declared primary behavior of synchronizing or repairing documentation under docs/. There are no file writes at all, no Markdown processing, and no invocation of md-sections. The actual purpose is narrower: change detection and reporting, not document sync/fix. Resource access is local and uses git only, which aligns with part of the description, but the main capability described is materially broader than what this code chunk actually does.

Content

No source excerpt is available for this finding.

Tp4

High
Category
MCP Tool Poisoning
Confidence
98% confidence
Finding

The declared description presents a higher-level doc-sync/remediation tool constrained to docs/ Markdown files and intended to compare code and docs for drift, possibly updating documentation. The actual code chunk is only the md-sections helper script, whose purpose is Markdown section extraction and navigation. While this helper could support the declared tool, on its own it materially differs from the declared primary purpose: it only reads a user-specified file, parses headings, outputs JSON or section text, and can operate on any file path, not just the declared docs/ whitelist. There are no sync, diff, repair, or code-vs-doc comparison behaviors in this chunk.

Content

No source excerpt is available for this finding.

Description-Behavior Mismatch

High
Category
Not specified by scanner
Confidence
97% confidence
Finding

The manifest claims there are no network requests, but later explicitly permits L3 semantic validation using a cloud LLM, which would transmit repository code and documentation to an external provider. This is dangerous because users may rely on the no-network claim when handling proprietary or sensitive code, leading to unintended data exfiltration outside the local environment.

Content

No source excerpt is available for this finding.

Scope Creep

High
Category
Not specified by scanner
Confidence
94% confidence
Finding

Although write scope is limited to docs/, the skill authorizes broad reads of source code, build files, repository metadata, and AI rule files such as AGENTS.md/CLAUDE.md. This expands the data-exposure surface significantly, and in combination with the L3 cloud-LLM path it can leak sensitive code, configuration, internal instructions, or other repository content beyond the narrow docs-sync purpose advertised to users.

Content

No source excerpt is available for this finding.

Ae1

High
Category
analysis-evasion
Confidence
100% confidence
Finding

Referenced artifact was not completely inspected

Content

Scanner excerpt · SKILL.md (reported line 100)May include surrounding context.

md
│ └─ 详细规则:references/verification-dimensions.md

Ae1

High
Category
analysis-evasion
Confidence
100% confidence
Finding

Referenced artifact was not completely inspected

Content

Scanner excerpt · SKILL.md (reported line 126)May include surrounding context.

md
│ └─ 详细规则:references/verification-dimensions.md

Ae1

High
Category
analysis-evasion
Confidence
100% confidence
Finding

Referenced artifact was not completely inspected

Content

Scanner excerpt · SKILL.md (reported line 237)May include surrounding context.

md
│ └─ 详细规则:references/verification-dimensions.md

Ae1

High
Category
analysis-evasion
Confidence
100% confidence
Finding

Referenced artifact was not completely inspected

Content

Scanner excerpt · SKILL.md (reported line 267)May include surrounding context.

md
│ └─ 详细规则:references/verification-dimensions.md

Ae1

High
Category
analysis-evasion
Confidence
100% confidence
Finding

Referenced artifact was not completely inspected

Content

Scanner excerpt · SKILL.md (reported line 355)May include surrounding context.

md
│ └─ 详细规则:references/verification-dimensions.md

Scope Creep

High
Category
Not specified by scanner
Confidence
98% confidence
Finding

The probing steps explicitly instruct access to root-level rule files, navigation configs, and build manifests outside the stated whitelist. In an agent setting, this broad filesystem discovery can collect sensitive operational guidance or project structure data unrelated to the requested task, increasing prompt-injection and data-exposure risk.

Content

No source excerpt is available for this finding.

Scope Creep

High
Category
Not specified by scanner
Confidence
97% confidence
Finding

The procedure explicitly instructs access to AGENTS.md and openspec/specs, which are outside the declared read/write scope and outside the stated docs-only synchronization boundaries. This creates a privilege/scope mismatch: an operator may believe the skill only touches docs/, while the procedure authorizes broader repository inspection that could expose sensitive instructions, secrets-in-docs, or unrelated internal design material.

Content

No source excerpt is available for this finding.

Scope Creep

High
Category
Not specified by scanner
Confidence
99% confidence
Finding

The file authorizes or expects access to many paths outside the declared whitelist, including source code, AGENTS.md, pom.xml, package.json, and application YAML files. Even if writes remain restricted, this broad undeclared read scope materially increases data exposure and breaks the user's stated expectation that the skill is confined to docs/ and local helper scripts.

Content

No source excerpt is available for this finding.

Description-Behavior Mismatch

High
Category
Not specified by scanner
Confidence
98% confidence
Finding

D8 institutionalizes processing of AGENTS.md even though the skill description says it only handles docs/ Markdown files. This is a real scope-expansion issue: once normalized in the verification workflow, an agent may inspect or act on control-plane documentation outside the declared boundary, undermining least privilege and making policy bypass easier.

Content

No source excerpt is available for this finding.

Undeclared Tool Scope

Medium
Category
MCP Least Privilege
Confidence
70% confidence
Finding

Without declared permissions the skill's intent is opaque and cannot be validated.

Content

No source excerpt is available for this finding.

Natural-Language Policy Violations

Medium
Category
Not specified by scanner
Confidence
89% confidence
Finding

The primary description and operating instructions are presented as Chinese-only behavior guidance, while the file does not state that language choice is optional or user-selected. Under the language/locale policy, forcing a specific language without opt-in is a natural-language policy concern unless the locale constraint is clearly justified.

Content

No source excerpt is available for this finding.

Vague Triggers

Medium
Category
Not specified by scanner
Confidence
93% confidence
Finding

The catch-all trigger for 'any scenario involving docs/code alignment' is overly broad and can cause the skill to activate in contexts the user did not explicitly request. Over-broad activation increases the chance of unnecessary repository scanning, unintended document edits, and accidental invocation of higher-risk phases such as multi-agent verification or cloud-backed semantic checks.

Content

No source excerpt is available for this finding.

Natural-Language Policy Violations

Medium
Category
Not specified by scanner
Confidence
81% confidence
Finding

The file title and the entire procedural content are written in Chinese, and there is no indication that users may choose another language or locale for skill execution. Under the policy rule, forcing a specific language without opt-in is a natural-language policy concern unless the locale restriction is explicitly documented and justified.

Content

No source excerpt is available for this finding.

Description-Behavior Mismatch

Medium
Category
Not specified by scanner
Confidence
97% confidence
Finding

The skill metadata promises a narrow local-docs scope, but the probing design expands read access to repository-wide files such as AGENTS.md, build files, README variants, and framework configs. That mismatch weakens least-privilege guarantees and can expose unrelated secrets, instructions, or sensitive project metadata to the agent under the guise of documentation sync.

Content

No source excerpt is available for this finding.

Context-Inappropriate Capability

Medium
Category
Not specified by scanner
Confidence
94% confidence
Finding

Accessing and preferring a script from $HOME extends trust beyond the target repository into user-environment state. That creates a local trust-boundary violation: a modified or unexpected home-directory script can influence skill behavior, execute unintended logic, or exfiltrate local context, despite the skill being presented as a local docs synchronizer.

Content

No source excerpt is available for this finding.

Natural-Language Policy Violations

Medium
Category
Not specified by scanner
Confidence
93% confidence
Finding

The file’s procedural instructions, headings, examples, and required report formats are entirely specified in Chinese, which imposes a specific language on users or operators. The document does not offer an opt-in language choice or explain that the skill is intentionally limited to a Chinese-language environment, so this is a natural-language locale policy issue.

Content

No source excerpt is available for this finding.

Intent-Code Divergence

Medium
Category
Not specified by scanner
Confidence
90% confidence
Finding

The L3 workflow expands from docs synchronization into broader semantic inspection of repository files such as AGENTS.md and OpenSpec materials, which exceeds the skill's declared docs-focused purpose. Scope expansion like this can cause the agent to inspect unrelated sensitive project content and violate least-privilege assumptions users rely on when invoking a docs-only tool.

Content

No source excerpt is available for this finding.

Natural-Language Policy Violations

Medium
Category
Not specified by scanner
Confidence
94% confidence
Finding

This markdown file is primarily written in Chinese and presents the skill instructions as a fixed Chinese-language reference manual, without indicating that users may choose another language or locale. That can violate language/locale policy when a skill implicitly forces one language without explicit opt-in or documented regional justification.

Content

No source excerpt is available for this finding.

Description-Behavior Mismatch

Medium
Category
Not specified by scanner
Confidence
95% confidence
Finding

The skill metadata claims it only operates on local Markdown files under docs/, but this guidance explicitly requires reading and analyzing AGENTS.md, which sits outside that stated scope. That mismatch weakens trust boundaries and can cause the agent to access repository metadata the user did not expect this skill to touch.

Content

No source excerpt is available for this finding.

Context-Inappropriate Capability

Medium
Category
Not specified by scanner
Confidence
86% confidence
Finding

D10 requires the LLM to deeply read code and perform semantic review, which goes beyond the described local-script-based doc drift detection workflow. This creates capability creep: the skill may perform broad, judgment-heavy inspection over codebases rather than the narrow deterministic synchronization users were told to expect.

Content

No source excerpt is available for this finding.

subprocess module call

Medium
Category
Dangerous Code Execution
Confidence
70% confidence
Finding

subprocess module calls execute external commands. Without careful input validation, this enables command injection.

Content

Scanner excerpt · scripts/detect-changes.py (reported line 134)May include surrounding context.

python
def run_git(*args: str, cwd: str | None = None) -> str:
    """Run a git command and return stripped stdout."""
    try:
        result = subprocess.run(
            ["git"] + list(args),
            capture_output=True,
            text=True,