---
name: oss-security-analysis
description: This skill should be used when the user asks to "audit this repo", "is this safe to run", "security audit", "check this clone", "audit security", "check for vulnerabilities", "scan for malicious code", "analyze security risks", "detect data exfiltration", or mentions security patterns, threat detection, or codebase safety assessment.
---

# OSS Security Analysis Skill

End-to-end audit workflow for evaluating the safety of open-source
repositories before running them locally. Covers pre-run safety, dependency
analysis, install script inspection, codebase pattern scanning, and report
generation.

## Audit Workflow

Run these five phases in order. Stop and report immediately if Phase 1
reveals critical risks. Otherwise complete all phases before scoring.

### Phase 1: Pre-Run Safety Check

**Goal:** Determine if it is safe to install dependencies or execute any
code from the repo. Do this BEFORE running any install or build commands.

1. **Identify the ecosystem** — look for `package.json`, `Gemfile`,
   `requirements.txt`, `pyproject.toml`, `Cargo.toml`, `go.mod`,
   `Makefile`, `CMakeLists.txt`, `setup.py`, `setup.cfg`.
2. **Check install hooks** (see Phase 3 details) — if install hooks run
   shell commands, flag them before proceeding.
3. **Check for Makefiles or build scripts** that execute on clone/setup —
   `Makefile` default targets, `configure` scripts, `.github/workflows/`
   that run on `pull_request`.
4. **Verdict:** Is it safe to install dependencies?
   - YES — proceed to Phase 2.
   - CONDITIONAL — install with `--ignore-scripts` (npm) or equivalent
     flag, then continue.
   - NO — report immediately, skip remaining phases.

### Phase 2: Dependency Analysis

**Goal:** Assess third-party dependency risk.

1. **Lockfile review** — check for lockfile presence (`package-lock.json`,
   `yarn.lock`, `pnpm-lock.yaml`, `Gemfile.lock`, `poetry.lock`,
   `Cargo.lock`, `go.sum`). Missing lockfiles increase supply-chain risk.
2. **Known CVEs** — run the ecosystem's audit tool if available:
   - Node.js: `npm audit --json` or `yarn audit --json`
   - Ruby: `bundle audit check` (if `bundler-audit` is available) or
     review `Gemfile.lock` manually
   - Python: `pip-audit` or `safety check`
   - Rust: `cargo audit`
   - Go: `govulncheck ./...`
   If the audit tool is not installed, note it and review lockfile entries
   manually for known-bad packages.
3. **Dependency count and freshness** — flag projects with very large
   dependency trees, unmaintained packages (no updates in 2+ years), or
   packages with very few downloads/stars.
4. **Typosquatting check** — compare package names against well-known
   packages for single-character substitutions or common misspellings.

### Phase 3: Install Script Inspection

**Goal:** Identify code that runs automatically during install or build.

#### Node.js / npm
- `preinstall`, `postinstall`, `prepare`, `prepublish` scripts in
  `package.json` — flag any that invoke `curl`, `wget`, `bash`, `sh`,
  `node -e`, or download remote content.
- Check `.npmrc` for `ignore-scripts=false` or custom registry URLs.

#### Python
- `setup.py` — look for `cmdclass` overrides, subprocess calls,
  or imports of `setuptools.command.install`.
- `pyproject.toml` — check `[tool.setuptools]` and build system hooks.

#### Ruby
- `Gemfile` — look for gems installed from git URLs (not rubygems.org).
- Gem extensions (`extconf.rb`, `Rakefile` in gem directories) that
  compile native code.

#### Rust / Go / C
- `build.rs` (Rust) — check for network calls or shell execution.
- `Makefile` / `CMakeLists.txt` — review default targets, `install`
  targets, and any `$(shell ...)` invocations.
- Go `generate` directives — `//go:generate` that run arbitrary commands.

### Phase 4: Codebase Pattern Scan

**Goal:** Detect malicious patterns, data exfiltration, and privacy
violations in the source code itself.

Use the detection categories and patterns below. For detailed regex/grep
patterns, consult `references/detection-patterns.md`.

#### Detection Categories

##### Network and Data Exfiltration

Patterns indicating unauthorized data transmission:

- Outbound HTTP/HTTPS requests to external URLs
- WebSocket connections to unknown endpoints
- DNS lookups to suspicious domains
- Email sending capabilities
- File upload mechanisms
- Encoded/encrypted data transmission
- Hardcoded IP addresses or domains

##### File System Access

Patterns indicating sensitive file access:

- Reading credential files (~/.ssh, ~/.aws, ~/.env, tokens)
- Accessing browser data (cookies, history, saved passwords)
- Reading system configuration files
- Unexpected file write operations
- Access to other applications' data directories

##### Code Execution Risks

Patterns enabling arbitrary code execution:

- Dynamic code evaluation (eval, exec, Function constructor)
- Shell command spawning (subprocess, spawn, popen)
- Dynamic imports or require statements
- Deserialization of untrusted data
- Template injection vulnerabilities

##### Obfuscation and Evasion

Patterns hiding malicious intent:

- Base64 encoded strings (especially URLs or commands)
- Hex-encoded payloads
- String concatenation to hide keywords
- Minified code without source maps
- Encrypted or packed code sections
- Anti-debugging techniques

##### Credential and Secret Handling

Patterns exposing sensitive data:

- Hardcoded API keys, tokens, or passwords
- Environment variable access patterns
- Keychain/credential store access
- Clipboard monitoring

### Phase 5: Report Generation

**Goal:** Produce a structured report with a clear safety verdict.

#### Output Format

1. **Executive Summary**: 2-3 sentence overview
2. **Overall Score**: Letter grade with numeric score
3. **Phase Results**:
   - Pre-run safety: PASS / CONDITIONAL / FAIL
   - Dependency analysis: finding count by severity
   - Install scripts: CLEAN / FLAGGED (with details)
   - Pattern scan: finding count by category
4. **Risk Categories**: Rating per category (Low/Medium/High/Critical)
5. **Critical Findings**: Highest-severity issues with evidence
6. **Warnings**: Medium-severity items
7. **Informational**: Low-severity or contextual findings
8. **Recommendations**: Specific mitigation actions
9. **Safe to Run?**: Clear YES / NO / CONDITIONAL verdict with conditions

#### Report Card Scoring

Generate a letter grade from A to F:

| Grade | Score | Meaning |
|-------|-------|---------|
| A | 90-100 | No significant concerns. Safe to run locally. |
| B | 80-89 | Minor concerns, low risk. Review flagged items. |
| C | 70-79 | Moderate concerns. Investigate before use. |
| D | 60-69 | Significant concerns. Multiple suspicious patterns. |
| F | <60 | Critical risks. Evidence of malicious intent. |

Scoring deductions:
- Critical finding: -25 points each
- High-risk finding: -10 points each
- Medium-risk finding: -5 points each
- Low-risk finding: -2 points each
- Missing lockfile: -5 points
- Install hooks with shell execution: -10 points
- Known CVEs (critical/high): -10 points each
- Known CVEs (medium/low): -3 points each

Start from 100 and subtract. Floor at 0.

## Risk Classification

### Critical (Immediate Report)

- Clear evidence of malicious code
- Active data exfiltration mechanisms
- Credential theft patterns
- Remote code execution backdoors

### High Risk

- Multiple suspicious patterns combined
- Obfuscated network communication
- Unauthorized file access to sensitive paths
- Install/postinstall scripts with shell execution

### Medium Risk

- Single suspicious pattern with legitimate use case possible
- Overly broad file access permissions
- Deprecated security practices
- Known CVEs with available patches

### Low Risk

- Minor security hygiene issues
- Missing best practices
- Informational findings

## Analysis Principles

- **Context matters**: A network library making HTTP requests is expected;
  a date formatter doing so is suspicious
- **Minimize false positives**: Distinguish between capability and intent
- **Consider attack chains**: Multiple low-severity findings may combine
  into high-severity risks
- **Preserve evidence**: Include exact file paths, line numbers, and code
  snippets for all findings
- **Fail fast on critical**: If clear malicious code is found, report
  immediately without completing remaining phases
- **Ecosystem awareness**: Different ecosystems have different norms —
  native extensions in Ruby gems are common, postinstall scripts in npm
  packages less so

## Additional Resources

### Reference Files

For detailed grep/regex patterns, consult:

- **`references/detection-patterns.md`** - Comprehensive regex and grep
  patterns for all detection categories, install script inspection, and
  false positive mitigation