@testzugang/pi-plugin-dependency-audit 0.1.0

package/README.md

@@ -0,0 +1,19 @@
+# @testzugang/pi-plugin-dependency-audit
+
+Static dependency and supply-chain malware auditing skill for Pi.
+
+## Install
+
+```bash
+pi install npm:@testzugang/pi-plugin-dependency-audit
+```
+
+## Usage
+
+```text
+/skill:dependency-audit
+```
+
+## Interactive Terminal Integration (Wrapper)
+
+See [SKILL.md](skills/dependency-audit/SKILL.md) for full instructions on setting up automated shell interception for security checks on `pi update`.

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@testzugang/pi-plugin-dependency-audit",
+  "version": "0.1.0",
+  "description": "Static dependency and supply-chain malware auditing skill for Pi",
+  "keywords": ["pi-package"],
+  "license": "MIT",
+  "files": [
+    "skills",
+    "README.md"
+  ],
+  "pi": {
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/skills/dependency-audit/README.md

@@ -0,0 +1,105 @@
+# npm/TypeScript Package Audit Skill
+
+Static-first Skill for reviewing TypeScript dependencies, npm packages and npm-based repositories before install or use.
+
+## What it does
+
+- Scans `package.json`, npm/pnpm/yarn lockfiles, `.npmrc`, TypeScript config, GitHub Actions and TS/JS source files.
+- Detects risky npm lifecycle scripts, Git/URL/File dependencies, optional dependency traps, bundled dependencies, non-default tarball sources and missing integrity.
+- Scans npm `.tgz` tarballs without executing package code.
+- Flags malware patterns such as download+execute, credential access+network, obfuscation, cloud metadata probes, GitHub API write behavior and IDE/AI-agent persistence.
+- Produces Markdown, JSON and SARIF output.
+
+## Quick start
+
+```bash
+python3 scripts/npm_ts_static_triage.py /path/to/repo-or-package.tgz \
+  --mode package \
+  --markdown npm-ts-audit.md \
+  --json npm-ts-audit.json \
+  --sarif npm-ts-audit.sarif \
+  --strict-exit
+```
+
+For global pi dependency checks without on-the-fly shell loops:
+
+```bash
+bash scripts/pi-check-current-global-versions.sh
+bash scripts/pi-check-latest-npm-versions.sh
+bash scripts/pi-check-git-source-updates.sh
+# or everything in one run
+bash scripts/pi-check-all-updates.sh
+
+# full static update audit + markdown summary
+python3 scripts/run_pi_dependency_audit.py --output /tmp/pi_audit_aggregated.json
+python3 scripts/summarize_pi_dependency_audit.py \
+  --input /tmp/pi_audit_aggregated.json \
+  --output /tmp/pi_audit_report.md
+```
+
+Age-gate configuration (default: 24h):
+
+- repo default: `skills/dependency-audit/config.json`
+- user override: `~/.pi/dependency-audit.json`
+- highest priority override: `--config /path/to/config.json`
+
+Example config:
+
+```json
+{
+  "min_update_age_hours": 24
+}
+```
+
+`--strict-exit` exits with code `2` for HIGH/CRITICAL findings and `1` for MEDIUM-only findings.
+
+## Safe package acquisition
+
+```bash
+npm view <package>@<version> name version dist.tarball dist.integrity dist.shasum time maintainers repository license --json
+curl -fL -o package-under-review.tgz '<dist.tarball-url>'
+sha256sum package-under-review.tgz
+python3 scripts/npm_ts_static_triage.py package-under-review.tgz --markdown report.md --json report.json --strict-exit
+```
+
+Do not run `npm install`, `npm ci`, `npm pack`, `npm test`, `npm run build`, `npx`, `node`, `tsx` or `ts-node` against untrusted code before static review.
+
+## Files
+
+- `SKILL.md`: full German skill instructions and policy.
+- `scripts/npm_ts_static_triage.py`: standalone stdlib-only scanner.
+- `scripts/pi-check-current-global-versions.sh`: reads installed versions for default/global pi packages.
+- `scripts/pi-check-latest-npm-versions.sh`: reads latest npm registry versions for default/global pi packages.
+- `scripts/pi-check-git-source-updates.sh`: compares local git checkouts with origin branch heads.
+- `scripts/pi-check-all-updates.sh`: runs all three checks in sequence.
+- `scripts/pi-default-packages.txt`: default package target list for the helper scripts.
+- `scripts/pi-default-git-repos.txt`: default git repo target list for update checks.
+- `scripts/run_pi_dependency_audit.py`: end-to-end static audit workflow for global pi dependency updates.
+- `scripts/summarize_pi_dependency_audit.py`: creates a markdown summary from aggregated JSON results.
+- `scripts/pi-interactive-update.py`: interactive CLI wrapper and menu selector for native `pi update` integration.
+- `config.json`: default config (currently `min_update_age_hours`).
+- `rules/iocs.txt`: editable IOC seed list.
+- `templates/report.md`: manual review template.
+- `examples/sample-commands.md`: safe commands and review playbooks.
+- `examples/github-actions-static-audit.yml`: example CI workflow for static-only scanning.
+
+## Interactive Shell Wrapper (`pi update` integration)
+
+To intercept the native `pi update` command in your terminal so it automatically runs this security audit first and prompts you with a selection menu of verified-safe updates, add the following wrapper function to your shell configuration (e.g., `~/.zshrc` or `~/.bashrc`):
+
+```bash
+# Wrapper for pi update to prepend dependency-audit and trigger interactive CLI selection
+pi() {
+    if [[ "$1" == "update" && ( -z "$2" || "$2" == "--extensions" ) ]]; then
+        python3 ~/.pi/agent/git/github.com/testzugang/pi-plugins/skills/dependency-audit/scripts/pi-interactive-update.py
+    else
+        command pi "$@"
+    fi
+}
+```
+
+After reloading your shell (`source ~/.zshrc`), typing `pi update` or `pi update --extensions` will launch the interactive audit menu before running any updates.
+
+## Important limitation
+
+A clean static report is not proof of safety. Use it as a pre-installation gate and combine it with registry metadata review, version cooldown, script suppression, provenance/signature checks, sandboxing and human review.

package/skills/dependency-audit/SKILL.md

@@ -0,0 +1,353 @@
+---
+name: dependency-audit
+description: Use when you need to audit an npm package, a GitHub repository, or pending dependency updates for supply-chain malware and risky lifecycle scripts before installation. Default action without parameters is to audit all pending updates.
+---
+
+# npm/TypeScript Package & Dependency Audit Skill
+
+## Ziel
+
+Nutze diesen Skill, wenn TypeScript-/JavaScript-Code, ein npm-Paket, ein GitHub-Repository, ein Dependency-Update oder ein npm-Lockfile vor der Nutzung geprüft werden soll. Der Fokus liegt auf Malware- und Supply-Chain-Erkennung vor `npm install`, `npm ci`, Build, Test, Import oder IDE-/CI-Ausführung.
+
+### Automatischer Workflow (ohne Parameter)
+
+Wenn der Skill ohne weitere Parameter aufgerufen wird (z.B. `/skill:dependency-audit`), muss **immer zuerst** eine explizite Modus-Auswahl über `user_select` erfolgen.
+
+Pflichtfrage (immer, als erster Schritt):
+
+- **"Pi-Dependencies prüfen"**
+- **"Projekt-Dependencies (aktuelles Verzeichnis) prüfen"**
+- **"Beides prüfen"**
+
+Regeln:
+
+1. Diese Auswahl darf nicht übersprungen werden, auch nicht bei fehlender `package.json`.
+2. Existiert bei Auswahl "Projekt-Dependencies" keine `package.json`, gib eine klare Rückfrage: Pfad angeben oder auf Pi-Dependencies wechseln.
+3. Starte keine Prüfung, bevor der Nutzer einen der drei Modi bestätigt hat.
+
+Führe dann je nach Auswahl die entsprechenden Szenarien aus:
+
+**Szenario A: Lokale npm-Abhängigkeiten**
+
+1. Führe `npm outdated --json` (oder ein äquivalentes Tool) aus, um die Liste verfügbarer Updates zu ermitteln.
+2. Iteriere durch die ermittelten Pakete.
+3. Führe für jedes Paket die in diesem Skill beschriebenen statischen Prüfungen durch.
+4. Generiere einen aggregierten Report.
+
+**Szenario B: Globale Pi-Erweiterungen**
+
+1. Nutze bevorzugt die mitgelieferten Hilfsskripte statt ad-hoc Bash-Loops:
+   - `scripts/pi-check-current-global-versions.sh`
+   - `scripts/pi-check-latest-npm-versions.sh`
+   - `scripts/pi-check-git-source-updates.sh`
+   - optional End-to-End: `scripts/run_pi_dependency_audit.py`
+2. Nutze die Config-Resolution für Sicherheitsrichtlinien (Priorität):
+   - `--config /path/to/config.json`
+   - `~/.pi/dependency-audit.json`
+   - `skills/dependency-audit/config.json`
+   - Fallback auf Defaults
+3. `min_update_age_hours` steuert die Mindest-Altersschwelle für Updates. Default ist `24`.
+4. Ermittle für jedes Paket, ob auf der Remote-Quelle (z. B. auf GitHub) neue Commits oder Versionen verfügbar sind.
+5. Wenn ein Update jünger als `min_update_age_hours` ist, markiere es als `too_fresh` mit `SKIP_TOO_FRESH`.
+6. Klone/lade die übrigen Updates temporär herunter, **ohne sie zu installieren oder Scripte auszuführen**.
+7. Führe die in diesem Skill beschriebenen statischen Prüfungen auf dem neuen Code durch.
+8. Generiere einen Report, der angibt, welche Pi-Erweiterungen sicher aktualisiert werden können. **Präsentiere am Ende des Berichts immer einen maßgeschneiderten nativen `pi update`-Vorschlag (siehe Abschnitt "Natives Pi-Paketmanagement (`pi update`)"), der blockierte/quarantänisierte oder zu frische Pakete explizit auslässt.**
+
+### Spezifischer Workflow (mit Parametern)
+
+Wenn der Skill mit einem Paketnamen oder einer Repository-URL aufgerufen wird, fokussiere die Prüfung ausschließlich auf dieses Ziel. Lade den Code in ein temporäres Verzeichnis herunter und wende die Prüfphasen statisch an.
+
+Der Skill ist bewusst auf npm und TypeScript zugeschnitten. Er prüft insbesondere:
+
+- `package.json`, `package-lock.json`, `npm-shrinkwrap.json`, `pnpm-lock.yaml`, `yarn.lock`, `.npmrc`.
+- npm-Lifecycle-Scripts wie `preinstall`, `install`, `postinstall`, `prepare`, `prepack`, `prepublish`.
+- `optionalDependencies`, Git-/URL-/File-Dependencies, Aliase, Overrides und Resolutions.
+- npm-Tarballs (`.tgz`) ohne Installation oder Script-Ausführung.
+- TypeScript-/JavaScript-Quellen, `dist/`, `lib/`, CLI-`bin`-Entrypoints und minifizierte/obfuskierte Dateien.
+- GitHub Actions und Publish-/Release-Workflows.
+- IDE-/AI-Agent-Poisoning über `.vscode`, `.claude`, `.cursor`, `.devcontainer`.
+- Qualität: Typisierung, `tsconfig`, Tests, Linting, Metadaten, Lockfile-Disziplin, Reproduzierbarkeit.
+
+## Threat Model
+
+Behandle jedes unbekannte npm-Paket und jede neue Dependency-Version als potenziell feindlich. Typische npm-/TS-Angriffe sind:
+
+1. **Install-Time Malware**: `preinstall`, `postinstall` oder `prepare` startet einen Downloader, Bootstrapper oder Token-Stealer.
+2. **Git-Dependency-Falle**: Eine scheinbar harmlose Dependency zeigt auf GitHub. Beim Installieren kann npm ein `prepare`-Script dieser Git-Dependency ausführen.
+3. **Optional-Dependency-Versteck**: Bösartiger Code liegt in `optionalDependencies`, wird leicht übersehen und kann bei Fehlern weniger auffallen.
+4. **Tarball-Poisoning**: Der veröffentlichte npm-Tarball enthält zusätzliche Dateien, die nicht im GitHub-Repo sichtbar sind.
+5. **Compiled JS Payload**: TypeScript-Repo wirkt sauber, aber `dist/`, `lib/` oder `setup.mjs` enthält obfuskierten JavaScript-Code.
+6. **Credential Harvesting**: Code sucht nach `GITHUB_TOKEN`, `NPM_TOKEN`, AWS-/Vault-/GitHub-Actions-OIDC-Secrets oder lokalen Dateien wie `.npmrc`, `.aws/credentials`, `.config/gh/hosts.yml`.
+7. **Repo-/IDE-Persistence**: Malware schreibt `.vscode/tasks.json`, `.claude/settings.json` oder ähnliche Konfigurationen, damit andere Entwickler oder AI-Coding-Agents später Code ausführen.
+8. **CI/CD-Missbrauch**: Workflows führen untrusted Code mit Write-Rechten, npm-Publish-Token oder OIDC-Rechten aus.
+
+## Sicherheitsvertrag
+
+Diese Regeln sind verbindlich:
+
+1. **Kein untrusted Code wird ausgeführt.** Kein `npm install`, `npm ci`, `npm test`, `npm run build`, `npx`, `pnpm install`, `yarn install`, `bun install`, `node setup.mjs`, `tsx`, `ts-node`, `docker build` oder ähnliches vor statischer Prüfung.
+2. **Kein `npm pack` aus einem untrusted Repo.** `npm pack` gehört zu den npm-Pack-Lifecycle-Abläufen und kann `prepack`, `prepare` und `postpack` betreffen. Für veröffentlichte Pakete lieber Registry-Metadaten lesen und den bereits veröffentlichten Tarball herunterladen.
+3. **Keine echten Secrets in der Analyseumgebung.** Vor der Prüfung keine GitHub-, npm-, AWS-, Azure-, GCP-, Vault- oder CI-Tokens exportieren.
+4. **Netzwerk ist standardmäßig aus.** Registry-/GitHub-Metadaten nur verwenden, wenn der Nutzer es erlaubt oder es zur Aktualitätsprüfung notwendig ist.
+5. **Artefakte immutable festhalten.** Repository immer auf exakten Commit-SHA; npm-Paket immer auf exakte Version und Tarball-Hash.
+6. **Script-Ausführung bleibt deaktiviert.** Review-Installationen nur mit `--ignore-scripts`, möglichst zusätzlich ohne optionale Dependencies.
+7. **Gefundene Secrets werden maskiert.** Nie komplette Tokens in Report, Chat, Logs oder Tickets ausgeben.
+8. **Jedes `CRITICAL` oder `HIGH` Finding blockiert Nutzung**, bis es manuell verifiziert, entfernt oder bewusst allowlisted wurde.
+
+## Eingaben
+
+Erfrage oder bestimme:
+
+- Paketname und Version, z. B. `@scope/pkg@1.2.3`, oder lokaler Repo-/Tarball-Pfad.
+- Exakter Git-Commit oder Release-Tag.
+- Nutzungsziel: Library, CLI, Frontend-App, Backend-Service, CI-Build, Production.
+- Package Manager: npm, pnpm, yarn oder bun. Dieser Skill bewertet primär npm-Semantik; pnpm/yarn-Lockfiles werden statisch mitgeprüft.
+- Ob Netzwerkzugriff für Registry-/GitHub-Metadaten erlaubt ist.
+- Ob es ein Dependency-Update ist; falls ja: alte Version, neue Version und Diff-Kontext.
+
+Wenn Angaben fehlen, führe eine konservative Best-Effort-Prüfung aus und dokumentiere Annahmen.
+
+## Ablauf
+
+### Phase 0: Secret-freie Analyseumgebung
+
+Nutze ein separates Verzeichnis oder eine Sandbox. Entferne Tokens aus der Shell:
+
+```bash
+unset GITHUB_TOKEN GH_TOKEN NPM_TOKEN NODE_AUTH_TOKEN AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN VAULT_TOKEN
+```
+
+Optional: Netzwerk in der Sandbox blockieren, sobald Artefakte vorliegen.
+
+### Phase 1: Artefakt beschaffen, ohne Code auszuführen
+
+#### GitHub-Repo
+
+```bash
+GIT_LFS_SKIP_SMUDGE=1 git clone --no-checkout <repo-url> repo-under-review
+cd repo-under-review
+git checkout --detach <exact-commit-sha-or-tag>
+git submodule status --recursive || true
+```
+
+Prüfe sofort `.gitmodules`, Workspaces, `package.json`, Lockfiles und `.github/workflows`.
+
+#### Veröffentlichtes npm-Paket
+
+Metadaten lesen, ohne Installation:
+
+```bash
+npm view <package>@<version> name version dist.tarball dist.integrity dist.shasum time maintainers repository license --json
+```
+
+Tarball herunterladen und Hash festhalten. Beispiel:
+
+```bash
+curl -fL -o package-under-review.tgz '<dist.tarball-url>'
+sha256sum package-under-review.tgz
+```
+
+Dann den Tarball mit dem mitgelieferten Scanner prüfen. Nicht installieren.
+
+### Phase 2: Automatisierte statische Triage
+
+```bash
+python3 scripts/npm_ts_static_triage.py /path/to/repo-or-package.tgz \
+  --mode package \
+  --markdown npm-ts-audit.md \
+  --json npm-ts-audit.json \
+  --sarif npm-ts-audit.sarif \
+  --strict-exit
+```
+
+Modi:
+
+- `package`: Standard für npm-Paket/Tarball.
+- `library`: TypeScript-Library; Version-Ranges sind weniger stark gewichtet, weil Libraries häufig Ranges nutzen.
+- `application`: App/Service; fehlende Lockfiles und Floating Ranges sind stärker relevant.
+- `repo`: allgemeines Repository-/Monorepo-Review.
+
+Der Scanner führt keinen Zielcode aus. Er extrahiert `.tgz`-Dateien sicher, folgt keinen Symlinks, scannt `package.json`, Lockfiles, npmrc, TS/JS-Dateien, Workflows und bekannte IoCs.
+
+### Phase 3: `package.json` manuell prüfen
+
+Blockiere oder eskaliere bei:
+
+- Install-Phase-Scripts: `preinstall`, `install`, `postinstall`, `prepublish`, `prepare`, `preprepare`, `postprepare`, `dependencies`.
+- Pack-/Publish-Scripts: `prepack`, `postpack`, `prepublishOnly`, `publish`, `postpublish`, wenn sie nicht trivial und dokumentiert sind.
+- Script-Inhalte mit `curl`, `wget`, `fetch`, `axios`, `got`, `node -e`, `eval`, `new Function`, `child_process`, `execSync`, `spawn`, `bun`, `python`, `bash`, `powershell`, `chmod +x`, Base64-/zlib-/AES-Decodern.
+- Kombinationen wie Download plus Execute, Secret-Zugriff plus Netzwerk oder `&& exit 1` nach Ausführung.
+- `optionalDependencies` mit `github:`, `git+`, `http(s)://`, `file:`, `link:` oder `npm:` Alias.
+- `overrides` oder `resolutions`, die transitive Dependencies auf Git-/URL-/File-Quellen umbiegen.
+- `bundleDependencies`/`bundledDependencies`, besonders `true`.
+- `bin`-Entrypoints, die auf obfuskierte oder fehlende Dateien zeigen.
+- `publishConfig.registry`, `.npmrc` oder Package-Metadaten, die auf nicht erwartete Registries zeigen.
+
+### Phase 4: Lockfile- und Dependency-Prüfung
+
+Prüfe:
+
+- `package-lock.json`-Einträge mit `hasInstallScript: true`.
+- `resolved`-Werte mit `git+`, `github:`, `http://`, nicht erwarteten Registries oder lokalen `file:`-Quellen.
+- Fehlende `integrity`-Werte bei Registry-Tarballs.
+- `optional: true` plus Install-Script oder Git-/URL-Quelle.
+- Neue oder stark geänderte transitive Dependencies im PR-Diff.
+- Lockfile fehlt bei Application-/CI-Projekten.
+
+Für pnpm/yarn-Lockfiles statisch nach `requiresBuild: true`, Git-/URL-Quellen und nicht erwarteten Registries suchen.
+
+### Phase 5: npm-Tarball-Inhalt prüfen
+
+Bei veröffentlichten Paketen ist der Tarball maßgeblich, nicht nur das GitHub-Repo. Prüfe im extrahierten Tarball:
+
+- Zusätzliche Dateien: `setup.mjs`, `install.js`, `postinstall.js`, `preinstall.js`, `router_init.js`, große `*.js`-Einzeiler.
+- Unterschiede zwischen Repo und Tarball.
+- Unerwartete `.npmrc`, `.vscode`, `.claude`, `.cursor`, `.devcontainer`, Git-Hooks oder Shell-Scripts.
+- Native Dateien: `.node`, `.so`, `.dll`, `.dylib`, `.exe`, `.wasm`.
+- Große minifizierte/obfuskierte Dateien mit `_0x...`, Base64-Blobs, `crypto.createDecipheriv`, `zlib.gunzipSync`, `eval`, `Function`.
+- `files`-Feld und `.npmignore`: Wird wirklich nur das erwartete Paket ausgeliefert?
+
+### Phase 6: Payload- und Exfiltrationsmuster
+
+Suche in TS/JS/MJS/CJS/CLI-Dateien nach Kombinationen:
+
+- Netzwerk: `fetch`, `http.request`, `https.get`, `axios`, `got`, `undici`, `curl`, `wget`, URL-Literale.
+- Ausführung: `child_process`, `exec`, `execSync`, `spawn`, `eval`, `new Function`, `vm.runInNewContext`, `WebAssembly.instantiate`.
+- Secrets: `process.env`, `GITHUB_TOKEN`, `NPM_TOKEN`, `NODE_AUTH_TOKEN`, `ACTIONS_ID_TOKEN`, AWS-/Vault-Variablen.
+- Lokale Credential-Dateien: `.npmrc`, `.aws/credentials`, `.config/gh/hosts.yml`, `.git-credentials`, `.netrc`, `.ssh`, `.docker/config.json`.
+- Cloud-/Vault-Probes: `169.254.169.254`, `metadata.google.internal`, `127.0.0.1:8200`.
+- GitHub API Write-Verhalten: `createCommitOnBranch`, `createRef`, `updateRef`, `repos/*/contents`, `api.github.com/graphql`.
+- IDE-/Agent-Pfade: `.claude/settings.json`, `.vscode/tasks.json`, `.cursor`, `.devcontainer`.
+
+Eine einzelne Netzwerk- oder Exec-Nutzung kann legitim sein. Die Kombination aus Netzwerk + Ausführung, Secret-Zugriff + Netzwerk oder IDE-Persistence + GitHub Write API ist ein Stop-Signal.
+
+### Phase 7: GitHub Actions und CI/CD
+
+Prüfe `.github/workflows/*.yml`:
+
+- `pull_request_target` mit Checkout oder `run:` von untrusted Code.
+- `workflow_run` mit Artefakt-Download und Ausführung.
+- `permissions: write-all` oder fehlende Minimalrechte.
+- `contents: write`, `packages: write`, `actions: write`, `id-token: write` ohne klare Begründung.
+- `npm install`/`npm ci` ohne `--ignore-scripts` in Review-/Dependency-Jobs.
+- `npm publish` mit `NPM_TOKEN`/`NODE_AUTH_TOKEN` aus nicht geschützten Branches.
+- Third-party Actions ohne full-length Commit-SHA.
+
+### Phase 8: TypeScript-/Package-Qualität
+
+Bewerte:
+
+- `tsconfig.json`: `strict`, `noImplicitAny`, `strictNullChecks`, `declaration` für Libraries.
+- `types`/`typings`, `exports`, `main`, `module` zeigen auf vorhandene Dateien.
+- Tests, Linting, Typecheck-Scripts und CI vorhanden.
+- README, LICENSE, SECURITY.md, Repository-Metadaten, `engines.node`.
+- Reproduzierbarkeit: Lockfile für Applications, dokumentierter Build, SBOM, Provenance/Attestations, Release-Tags.
+- Keine unklare generierte Ausgabe in `dist/` ohne nachvollziehbare Quelle.
+- Dependency-Policy: Cooldown für neue Versionen, Renovate/Dependabot mit menschlichem Review, Allowlist für Scripts und non-registry Sources.
+
+## Sichere Installation nach Freigabe
+
+Erst nach statischer Prüfung und manueller Freigabe:
+
+```bash
+npm ci --ignore-scripts --omit=optional
+npm audit --audit-level=high
+npm audit signatures
+```
+
+Für Review-Installationen optional zusätzlich moderne npm-Quellbeschränkungen nutzen, falls unterstützt:
+
+```bash
+npm ci --ignore-scripts --omit=optional --allow-git=none --allow-remote=none --allow-file=none
+```
+
+Wenn ein Paket legitime Native Builds oder Install-Scripts braucht, erst eine minimale Allowlist definieren, dann in einer Sandbox ohne Secrets ausführen.
+
+## Natives Pi-Paketmanagement ("pi update")
+
+Pi verwaltet Erweiterungen, Skills, Prompt-Templates und Themes nativ über Paket-Definitionen in `~/.pi/agent/settings.json` (unter `"packages"`) unter Verwendung der Protokolle `npm:` und `git:`.
+
+- **npm-Pakete (`npm:pkg-name`)**: Werden global (`npm install -g`) oder projektlokal unter `.pi/npm/` installiert.
+- **Git-Pakete (`git:github.com/user/repo`)**: Werden global nach `~/.pi/agent/git/<host>/<path>` geklont. Nach jedem `git pull` führt Pi automatisch `npm install` im geklonten Verzeichnis aus.
+
+### Erstellung des Update-Vorschlags im Report
+
+Der Auditor muss am Ende des Berichts **immer** den passenden, maßgeschneiderten Befehl zur Durchführung der sicheren Updates vorschlagen:
+
+1. **Ausschluss-Regel**: Blockierte/quarantänisierte Pakete und zu frische Pakete (`too_fresh`, die die Altersschwelle `min_update_age_hours` unterschritten haben) dürfen **niemals** im Update-Vorschlag enthalten sein.
+2. **Spezifischer Update-Vorschlag (Chaining)**: Wenn einzelne Pakete aufgrund von Sicherheitsbedenken oder Altersschwellen ausgelassen werden müssen, generiere einen verketteten Einzelupdate-Befehl mittels `&& \`, um nur die verifizierten Pakete gezielt zu aktualisieren:
+   ```bash
+   pi update npm:pi-mcp-adapter && \
+   pi update npm:pi-total-recall && \
+   pi update git:github.com/fgladisch/pi-skills
+   ```
+3. **Komplett-Update (Sammelbefehl)**: Wenn alle anstehenden Updates sicher sind und kein Paket ausgelassen werden muss, schlage den Sammelbefehl vor:
+   ```bash
+   pi update --extensions
+   ```
+
+### Interaktive Terminal-Integration (Wrapper)
+
+Um den standardmäßigen `pi update` Befehl im Terminal abzufangen, sodass er automatisch diesen interaktiven Sicherheits-Audit triggert und eine interaktive Auswahl anbietet, kann folgende Shell-Funktion in die Shell-Konfiguration (z. B. `~/.zshrc` oder `~/.bashrc`) eingetragen werden:
+
+**If installed via GitHub/Git (legacy):**
+```bash
+pi() {
+    if [[ "$1" == "update" && ( -z "$2" || "$2" == "--extensions" ) ]]; then
+        python3 ~/.pi/agent/git/github.com/testzugang/pi-plugins/skills/dependency-audit/scripts/pi-interactive-update.py
+    else
+        command pi "$@"
+    fi
+}
+```
+
+**If installed via npm:**
+```bash
+pi() {
+    if [[ "$1" == "update" && ( -z "$2" || "$2" == "--extensions" ) ]]; then
+        python3 ~/.pi/packages/node_modules/@testzugang/pi-plugin-dependency-audit/skills/dependency-audit/scripts/pi-interactive-update.py
+    else
+        command pi "$@"
+    fi
+}
+```
+
+Nach dem Neuladen der Shell (`source ~/.zshrc`) führt jede Eingabe von `pi update` oder `pi update --extensions` direkt zu dem interaktiven Audit-Menü.
+
+## Severity-Regeln
+
+- `CRITICAL`: bekannte IoC, Credential-Exfiltration, Download+Execute, Secret-Zugriff+Netzwerk, IDE-/Agent-Persistence mit GitHub-Write, Path-Traversal im Tarball, live Token im Paket.
+- `HIGH`: Install-Phase-Lifecycle-Scripts, Git-/URL-/File-Dependencies in `optionalDependencies`, unpinned Git-Dependencies, obfuskierter Lifecycle-Entrypoint, CI mit untrusted Code und Write-/Publish-Rechten.
+- `MEDIUM`: Lockfile-Einträge mit Install-Scripts, non-default Registries, fehlende Integrity, bundled Dependencies, risky Scripts ohne klare Exfil-Kombination, fehlender Lockfile bei Apps.
+- `LOW`: Qualitäts-/Hygieneprobleme, fehlende Metadaten, schwache TS-Konfiguration, fehlende Security-Dateien.
+- `INFO`: Inventar, Workspaces, neutrale Beobachtungen.
+
+## Stop-Regeln
+
+Empfehlung sofort auf **nicht nutzen / Quarantäne**, wenn eines zutrifft:
+
+- Known IOC im Manifest, Lockfile oder Code.
+- Lifecycle-Script lädt Code/Binaries nach und führt sie aus.
+- Datei kombiniert `child_process`/`eval` mit `fetch`/HTTP/Download.
+- Code liest Tokens oder Credential-Dateien und hat Netzwerk- oder GitHub-API-Zugriff.
+- `optionalDependencies` zeigen auf GitHub/Git/URL und können `prepare` auslösen.
+- npm-Tarball enthält unerwartete IDE-/Agent-Konfigurationen.
+- Workflow kann untrusted Code mit `NPM_TOKEN`, GitHub Write-Rechten oder OIDC ausführen.
+
+## Reportformat
+
+Jeder Befund enthält:
+
+- Severity.
+- Kategorie.
+- Datei und Zeile.
+- Evidence, kurz und maskiert.
+- Warum riskant.
+- Empfohlene Maßnahme.
+- Status: `confirmed`, `needs-human-review`, `false-positive-candidate`.
+
+Nutze `templates/report.md` für manuelle Reviews und die Reports des Scanners für automatisierte Runs.
+
+## Grenzen des Skills
+
+Ein sauberer statischer Report beweist nicht, dass ein Paket sicher ist. Er reduziert Früh-Risiko vor Installation und Ausführung. Stark verschleierte Payloads, polymorphe Malware, native Binaries, absichtlich harmlose Stubs mit späterem Remote-Update und Registry-/Account-Kompromisse können zusätzliche manuelle oder sandboxed Analyse erfordern.

package/skills/dependency-audit/config.json

@@ -0,0 +1,3 @@
+{
+  "min_update_age_hours": 24
+}

package/skills/dependency-audit/examples/github-actions-static-audit.yml

@@ -0,0 +1,46 @@
+name: npm TypeScript static package audit
+
+on:
+  pull_request:
+    paths:
+      - "package.json"
+      - "package-lock.json"
+      - "npm-shrinkwrap.json"
+      - "pnpm-lock.yaml"
+      - "yarn.lock"
+      - "src/**"
+      - "dist/**"
+      - "lib/**"
+      - ".github/workflows/**"
+      - ".npmrc"
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  static-audit:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@0000000000000000000000000000000000000000 # Replace with the real full-length commit SHA for actions/checkout
+        with:
+          persist-credentials: false
+
+      - name: Run static audit
+        run: |
+          python3 scripts/npm_ts_static_triage.py . \
+            --mode repo \
+            --markdown npm-ts-audit.md \
+            --json npm-ts-audit.json \
+            --sarif npm-ts-audit.sarif \
+            --strict-exit
+
+      - name: Upload audit artifacts
+        if: always()
+        uses: actions/upload-artifact@0000000000000000000000000000000000000000 # Replace with the real full-length commit SHA for actions/upload-artifact
+        with:
+          name: npm-ts-audit
+          path: |
+            npm-ts-audit.md
+            npm-ts-audit.json
+            npm-ts-audit.sarif

package/skills/dependency-audit/examples/sample-commands.md

@@ -0,0 +1,110 @@
+# Safe npm/TypeScript audit commands
+
+## 1. Scan a local repository without installing dependencies
+
+```bash
+python3 scripts/npm_ts_static_triage.py /path/to/repo \
+  --mode repo \
+  --markdown repo-audit.md \
+  --json repo-audit.json \
+  --sarif repo-audit.sarif \
+  --strict-exit
+```
+
+## 2. Scan a published npm tarball
+
+```bash
+npm view @scope/package@1.2.3 name version dist.tarball dist.integrity dist.shasum time maintainers repository license --json > package-metadata.json
+jq -r '.dist.tarball' package-metadata.json
+curl -fL -o package-under-review.tgz "$(jq -r '.dist.tarball' package-metadata.json)"
+sha256sum package-under-review.tgz
+python3 scripts/npm_ts_static_triage.py package-under-review.tgz --mode package --markdown package-audit.md --json package-audit.json --strict-exit
+```
+
+## 3. Compare two package tarballs without running npm scripts
+
+```bash
+mkdir -p old new
+python3 - <<'PY'
+import tarfile, pathlib
+for src, dst in [('old.tgz', 'old'), ('new.tgz', 'new')]:
+    with tarfile.open(src, 'r:*') as tf:
+        tf.extractall(dst, filter='data')
+PY
+diff -ruN old/package new/package > package-diff.patch || true
+```
+
+Review the diff for new `scripts`, `optionalDependencies`, `setup.mjs`, generated JS, hidden config and native binaries.
+
+## 4. Safe review install after static approval
+
+```bash
+npm ci --ignore-scripts --omit=optional
+npm audit --audit-level=high
+npm audit signatures
+```
+
+Only run required lifecycle scripts later in a sandbox without secrets, after the exact package and script have been allowlisted.
+
+## 5. Harden npm defaults for a review environment
+
+```bash
+npm config set ignore-scripts true
+npm config set audit true
+npm config set fund false
+npm config set save-exact true
+npm config set strict-ssl true
+```
+
+If your npm version supports source restrictions, use them for review jobs:
+
+```bash
+npm ci --ignore-scripts --omit=optional --allow-git=none --allow-remote=none --allow-file=none
+```
+
+## 6. Common manual grep commands
+
+```bash
+grep -RInE 'preinstall|postinstall|prepare|prepack|bundleDependencies|optionalDependencies' package.json package-lock.json pnpm-lock.yaml yarn.lock 2>/dev/null || true
+grep -RInE 'child_process|execSync|spawn\(|eval\(|new Function|fetch\(|https?://|curl|wget|169\.254\.169\.254|GITHUB_TOKEN|NPM_TOKEN|VAULT_TOKEN|\.npmrc|\.aws/credentials|createCommitOnBranch|\.claude|\.vscode/tasks\.json' . --exclude-dir=.git --exclude-dir=node_modules 2>/dev/null || true
+find . -type f \( -name '*.js' -o -name '*.mjs' -o -name '*.cjs' -o -name '*.ts' -o -name '*.tsx' \) -size +500k -print
+```
+
+## 7. Reusable helpers for global pi dependency checks
+
+```bash
+# current installed versions
+bash scripts/pi-check-current-global-versions.sh
+
+# latest npm versions
+bash scripts/pi-check-latest-npm-versions.sh
+
+# git-based source updates for local checkouts
+bash scripts/pi-check-git-source-updates.sh
+
+# all checks in one call
+bash scripts/pi-check-all-updates.sh
+```
+
+Each helper accepts optional package/repo arguments to override defaults.
+
+## 8. End-to-end global pi update audit (static only)
+
+```bash
+python3 scripts/run_pi_dependency_audit.py --output /tmp/pi_audit_aggregated.json
+python3 scripts/summarize_pi_dependency_audit.py \
+  --input /tmp/pi_audit_aggregated.json \
+  --output /tmp/pi_audit_report.md
+
+# Optional: use custom config (highest precedence)
+python3 scripts/run_pi_dependency_audit.py \
+  --config /path/to/dependency-audit.json \
+  --output /tmp/pi_audit_aggregated.json
+```
+
+## 9. Review outcome policy example
+
+- CRITICAL: quarantine, do not install, rotate any exposed credentials.
+- HIGH: block until a human reviewer approves a documented fix or allowlist.
+- MEDIUM: review before use; may pass with documented rationale.
+- LOW/INFO: track as hygiene improvements.