Hypershell-34 add security tools

[kdoberst]

Summary

This PR adds agent skill security tooling and a cleaner APM install path for HyperShell.

It covers three related pieces:

1. Optional deep security audits via a new /run-security-audit skill
2. Safer day-to-day APM setup with make apm-install (install + Skillspector scan)
3. Selected ProdSec skills pulled in through APM for optional use

Refs: HYPERSHELL-34

---

Background (APM & Skillspector)

APM (Agent Package Manager) is how this repo declares and installs shared agent skills from upstream packages (similar in spirit to a dependency manager, but for AI agent skills rather than runtime libraries).

Skillspector is a static security scanner for agent skills. It looks for risky patterns in skill code/scripts (for example unsafe subprocess usage). Findings can be suppressed via a baseline file so known false positives do not fail future scans.

---

What changed

1. Optional AI security harness skill (/run-security-audit)

Adds skills/security/run-security-audit, which bootstraps Red Hat’s internal ai-security-harness on demand and runs threat modeling / secure code audit against this repo.

Why this is not an APM dependency

The harness is intentionally not installed via APM for three reasons:

• The harness repo is not currently in a shape APM can consume cleanly
• It lives on internal GitLab and needs auth that not every contributor has (this is an open-source repo)
• Its skills depend heavily on sibling files, making a partial APM import unreliable

How it works instead

• The skill clones/updates the harness git repo when run
• It is optional — only needed by people who have access and want a deep audit
• Requires two environment variables:
  • GITLAB_HOST=gitlab.cee.redhat.com
  • GITLAB_APM_PAT=<PAT with read_repository on the harness project>
• Expect a long runtime and a high-capability model (e.g. mythos-class / Claude Opus). Lighter models will underperform on the methodology.

Because the harness is no longer an APM dependency, apm install can run cleanly for everyone without worrying about GitLab auth.

2. make apm-install + Skillspector baseline

Adds a Makefile target so contributors do not need to know raw APM/Skillspector commands:

make apm-install

That runs scripts/apm-install.sh, which:

• Ensures APM is available (installs it if missing)
• Runs apm install
• Ensures Skillspector is available (tries uv/pipx install if missing)
• Scans imported + repo skills with Skillspector
• Uses .skillspector-baseline.yaml so known false positives / non-skill paths are ignored

Also adds make apm-audit for the audit path declared in apm.yml.

Open question: whether apm-install should later be folded into another Make target. For now it is standalone so the install/scan flow stays explicit and easy to discover.

3. Selected ProdSec skills via APM

ProdSec maintains a large skill catalog. Pulling everything in was not practical, so only a small, clearly useful subset is declared in apm.yml:

• go-security
• tls-compliance
• database-security
• react-security
• helm-chart-security
• linux-capabilities

These are available after make apm-install, but they are not wired into other workflows yet. Review by people familiar with HyperShell’s code/security posture should happen before hooking them into CI, reconcile, or other automated flows.

---

Test plan

• Run make apm-install on a clean machine/clone and confirm APM deps install
• Confirm Skillspector runs and exits cleanly against the existing baseline (no unexpected HIGH/CRITICAL)
• Confirm apm install succeeds without GitLab credentials
• (Optional, access required) Set GITLAB_HOST + GITLAB_APM_PAT and run /run-security-audit in a supported mode (threat-model, code-audit, or full)
• Spot-check that the newly imported ProdSec skills appear under APM modules / skill paths after install

[rh-amarin]

This failed for me, Claude added this

⎿  Added 1 line, removed 1 line
67 - --output "$SCAN_OUT"
67 + --output "$SCAN_OUT" || true

⏺ What was happening: skillspector scan found findings and exited with code 1. Because of set -euo pipefail, the script died right there — the python3
severity filter (which was designed to pass LOW/MEDIUM and only fail on HIGH/CRITICAL) never ran.

The fix: || true lets skillspector scan exit non-zero without aborting the script, so the python3 block can do its job — filtering by severity and only
failing if there are actual HIGH/CRITICAL findings.

[rh-amarin]

Run it once in my local and gave me a couple of security warnings

=========================================
   SECURITY: HIGH/CRITICAL findings detected
  =========================================
    HIGH: PE3 in tests/e2e/drivers/kind.sh:81 - Credential Access
    HIGH: TM2 in .github/workflows/e2e.yml:204 - Chaining Abuse
Review these findings and either fix them or add to .skillspector-baseline.yaml
  make: *** [apm-install] Error 1

Then Calude analyzed the result and concluded that:

Both findings are false positives in test/CI files:

1. PE3 in kind.sh:81 — acquire_oidc_token function for e2e tests getting a token from a local Keycloak; that's standard test infrastructure, not credential theft.
2. TM2 in e2e.yml:204 — curl | sh to install openshell CLI from a known first-party repo; flagged as "chaining abuse" but it's a standard install pattern in CI.

Both files are already in directories that should be excluded (tests/ and .github/), but the baseline only covers scripts/* and components/*, not those paths.

It suggests to add exclusions:

- path: "tests/*"
   reason: "Test code - not agent skills"
- path: ".github/*"
   reason: "CI workflow definitions - not agent skills"

[kdoberst]

Addresses PR feedback around APM install, SkillSpector scanning, and the /run-security-audit skill.

SkillSpector / make apm-install

• scripts/apm-install.sh

  • Stops auto-installing APM and SkillSpector; prints a prerequisite checklist instead and fails fast if required tools are missing.
  • SkillSpector is optional for local make apm-install (warn + exit 0 if missing); --force requires it for CI.
  • Saves JSON reports to .skillspector-reports/scan-results-<epoch>.json instead of a temp file that was deleted on exit.
  • Prints the report path on pass/fail; uses a heredoc for safer Python parsing.

• .skillspector-baseline.yaml

  • Baselines three e2e/CI false positives: E2 (OIDC token setup in e2e), PE3 (Keycloak test credentials in Kind driver), TM2 (curl | sh for OpenShell in e2e workflow).
  • Excludes .skillspector-reports/* so scan output is not analyzed as source.

• .gitignore - ignores .skillspector-reports/

• Makefile - adds make apm-install-force for CI (requires SkillSpector)

/run-security-audit skill

• SKILL.md / README.md
  • Adds Step 0: prerequisite check with checklist; skill stops if required tools (git, python3, pip/uv) are missing.
  • Separates required vs optional scanner tools; optional tools still improve coverage but no longer block the audit.
  • Renumbers later steps; pre-scanner availability now comes from Step 0 instead of a separate check.
  • Replaces em dashes with normal hyphens for repository policy compliance.

Other

• apm.lock.yaml - refreshed lockfile (resolved_ref fields added per APM update)