Huawei Cloud Skill Audit

Two-check security pipeline for auditing Huawei Cloud skills — security gate.

Overview

Scan a single Huawei Cloud skill directory or a folder of skills, run two security gates, and generate a structured report with issue details and fix strategies.

Two checks:

Prerequisites

1. Python 3.10+ — Required by skillcheck; Python 3.12+ for external skillspector binary (builtin has no Python version restriction)
2. Node.js + npx — Required by markdownlint-cli2
3. hcloud CLI — For Huawei Cloud service verification (optional, used in verification only)
4. Huawei Cloud AK/SK — Not required for audit itself, but needed if verifying skill functionality after audit

skillspector and gitleaks are built-in (pure Python) — no external binary or pip install needed. External binaries are used as fallback if available on PATH.

Tools are auto-installed on first run (only skillcheck and markdownlint-cli2). If you prefer manual install:

pip install skillcheck
npm install -g markdownlint-cli2

To skip auto-install, use --no-install flag.

Workflow

Input (skill path or folder)
    │
    ├── Discover Skills ──── Find SKILL.md in target or subdirectories
    │
    ├── Run Two Checks ────
    │   1. skillspector → AI security scan (47 rules, 439 patterns)
    │   2. gitleaks → Credential leak detection
    │
    ├── Build Report ────
    │   Section 1: Scanned Skills
    │   Section 2: Issue Summary (by severity)
    │   Section 3: Issue Details (per-issue)
    │   Section 4: Fix Strategies (per rule/category)
    │
    └── Gate Verdict ──── PASS or FAIL

Scan Levels

Severity filtering applies only to SkillSpector. gitleaks, hwcloud-spec, skillcheck, and markdownlint always report all findings regardless of scan level.

KooCLI Command Format Standard

This skill does not directly invoke hcloud CLI commands. It audits skill directories locally. However, when verifying a skill's functionality after audit, the standard KooCLI format applies:

hcloud <Service> <Operation> --cli-region=<region> [--key=value ...]

Core Commands

Scan a single skill

python3 scripts/skill_audit.py --target /path/to/my-skill

Scan a folder of skills

python3 scripts/skill_audit.py --target /path/to/skills-folder

Scan with specific level

python3 scripts/skill_audit.py --target /path/to/skills --scan-level quick

Selective check execution

python3 scripts/skill_audit.py --target /path/to/skills --checks skillspector
python3 scripts/skill_audit.py --target /path/to/skills --skip-checks markdownlint

Run with custom tool paths

python3 scripts/skill_audit.py \
  --target /path/to/skill-or-folder \
  --scan-level standard \
  --skillspector /path/to/skillspector \
  --gitleaks /path/to/gitleaks \
  --node-bin /opt/nvm/versions/node/v18.20.8/bin

Available --scan-level values: critical (default), high, quick, standard, deep. Available --checks: skillspector, gitleaks. Use --skip-checks to exclude specific checks.

Parameter Confirmation

Report Structure

Report is saved as skill-gate-report-<timestamp>.txt in the parent directory of the scanned path.

Four sections:

1. Scanned Skills — list of all skills found
2. Issue Summary — count by severity (CRITICAL/ERROR/WARNING) with rule breakdown (INFO excluded)
3. Issue Details — per-issue: skill name, rule, line number, snippet, message
4. Fix Strategies — actionable remediation for each unique rule/category

Fix Strategies Reference

hwcloud-spec (Huawei Cloud SKILL.md Spec)

markdownlint-cli2

skillspector

gitleaks

Remediation Workflow (audit -> fix -> verify)

After running the audit and getting a FAIL, follow this sequence:

1. Run markdownlint-cli2 --fix FIRST — auto-fixes MD022/MD031/MD032/MD047/MD012/MD009/MD010 and many more.

   markdownlint-cli2 "skills/my-skill/**/*.md" --config "skills/my-skill/.markdownlint.json" --fix
   

   2. Fix hwcloud-spec missing sections — Add required sections by hand (require domain knowledge).

   3. Fix MD036 (emphasis-as-heading) — Replace *text* or **text** pseudo-heading with ### heading or plain text.

   4. Fix MD040 (fenced-code-language) — Replace bare ``` with ```text or the appropriate language.

   5. Run markdownlint-cli2 --fix AGAIN — Catch new issues from manual edits.

   6. Re-run the full audit to verify PASS.

CI/CD Integration

jobs:
  skill-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g markdownlint-cli2
      - name: Run audit
        run: python3 scripts/skill_audit.py --target . --output-dir .
      - name: Upload report
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: skill-gate-report
          path: skill-gate-report-*.txt

Configuration Files

skillcheck.toml

[frontmatter]
extension_fields = [
    "license",
    "platforms",
    "metadata",
    "prerequisites",
]

.markdownlint.json

{
  "default": true,
  "MD003": { "style": "atx" },
  "MD004": { "style": "dash" },
  "MD013": { "line_length": 200, "code_blocks": false, "tables": false },
  "MD024": { "siblings_only": true },
  "MD033": false,
  "MD034": false,
  "MD040": false,
  "MD041": false,
  "MD046": false,
  "MD047": false,
  "MD058": false
}

Security Scanning

Why skillspector static-only mode has limitations

skillspector runs with --no-llm mode (static analysis only). Gaps:

Complementary tools

Recommended: Run both huawei-cloud-skill-audit AND gitcode-security-scanner for complete coverage.

Output Format

Report is a plain text file with four sections (Scanned Skills, Issue Summary, Issue Details, Fix Strategies) followed by a Gate Verdict (PASS/FAIL).

Verification Method

Run audit

python3 scripts/skill_audit.py --target /path/to/skill

Verify fix

# Auto-fix markdownlint issues
markdownlint-cli2 "/path/to/skill/**/*.md" --config "/path/to/skill/.markdownlint.json" --fix

# Re-run audit
python3 scripts/skill_audit.py --target /path/to/skill

Check gate verdict

# Gate Verdict: PASS = all checks passed
# Gate Verdict: FAIL = one or more checks have issues

Reference Documents

• references/iam-policies.md — IAM permissions required for skill audit
• references/verification-method.md — Detailed verification procedures
• references/acceptance-criteria.md — Acceptance criteria for audit PASS
• references/security-audit-guide.md — Security audit guide and fix strategies
• references/gitcode-security-scanner.md — Complementary scanner usage guide

Best Practices

• Run audit before accepting any Huawei Cloud skill contribution
• Fix markdownlint issues with --fix first, then fix non-auto-fixable items manually
• Always re-run full audit after fixing to verify PASS
• For large repos, scan individual skills one at a time to avoid huge reports
• Run both huawei-cloud-skill-audit and gitcode-security-scanner for complete security coverage

Notes

• Five-check pipeline runs sequentially; each check is independent
• API endpoints are strictly prohibited from being inferred
• Credentials (AK/SK) are read from environment variables; hardcoding is prohibited
• If AK/SK is missing for post-audit verification, prompt the user; do not skip
• Resources created during testing must be tracked; output manual cleanup instructions if any remain
• INFO-level issues are excluded from the report; only CRITICAL/ERROR/WARNING appear
• gitleaks --no-git mode scans current file contents only, not git history
• gitleaks does not detect Chinese keyword credentials; use gitcode-security-scanner for those

Edge Cases

Design Principles

• Two-Check Pipeline — Each check is independent and contributes to the overall gate verdict
• Auto-Install — Missing tools are installed automatically on first run
• Chain Verification — All five checks must pass for gate verdict PASS
• Agent-proof — Write operations require user confirmation; automatic gate bypassing is not allowed
• Data-Driven — Report is structured text with clear severity levels and fix strategies
• Batch Repeatable — Same skill can be audited repeatedly; --fresh resets
• Credential Security — No hardcoded AK/SK; read from environment variables
• Least Privilege — IAM policies follow minimum required permissions