LeoYeAI/agent-master-skills / skills/agentaudit
agentaudit-skill
FlaggedAutomatic security gate that checks packages against a vulnerability database before installation. Use before any npm install, pip install, yarn add, or package manager operation.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 33.7 KB |
| SKILL.md | skill md | 18.0 KB |
| _meta.json | config | 631 B |
| config/credentials.json | config | 89 B |
| install.sh | script | 5.7 KB |
| prompts/audit-prompt.md | markdown | 36.6 KB |
| prompts/review-prompt.md | markdown | 2.8 KB |
| references/API-REFERENCE.md | markdown | 4.1 KB |
| references/AUDIT-METHODOLOGY.md | markdown | 6.8 KB |
| references/DETECTION-PATTERNS.md | markdown | 5.9 KB |
| references/REPORT-FORMAT.md | markdown | 5.0 KB |
| references/TROUBLESHOOTING.md | markdown | 4.4 KB |
| references/TRUST-SCORING.md | markdown | 2.2 KB |
| scripts/_curl-retry.sh | script | 850 B |
| scripts/_load-key.sh | script | 1.6 KB |
| scripts/check.mjs | script | 6.3 KB |
| scripts/check.sh | script | 5.7 KB |
| scripts/gate.mjs | script | 5.1 KB |
| scripts/gate.sh | script | 4.9 KB |
| scripts/register.mjs | script | 4.7 KB |
| scripts/register.sh | script | 3.4 KB |
| scripts/rotate-key.sh | script | 2.3 KB |
| scripts/upload.mjs | script | 7.3 KB |
| scripts/upload.sh | script | 8.4 KB |
| scripts/verify.sh | script | 3.6 KB |
references/TROUBLESHOOTING.md
View on GitHub# Troubleshooting Guide
Common issues and edge cases when using AgentAudit.
## Error Handling & Edge Cases
| Situation | Behavior | Rationale |
|-----------|----------|-----------|
| API down (timeout, 5xx) | **Default-warn** (exit 2). Agent pauses, shows warning: "AgentAudit API unreachable. Cannot verify package safety. Retry in 5 minutes or proceed at your own risk?" Package is NOT auto-installed. | Security over convenience |
| Upload fails (network error) | Retry once. If still fails, save report to `reports/<package>-<date>.json` locally. Warn user. | Don't lose audit work |
| Hash mismatch | **Hard stop.** But note: could be a legitimate update if package version changed since last audit. Check if version differs → if yes, re-audit. If same version → likely tampered. | Version-aware integrity |
| Rate limited (HTTP 429) | Wait 2 minutes, retry. If still limited, save locally and upload later. | Respect API limits |
| No internet | Warn user: "No network access. Cannot verify against AgentAudit registry. Proceeding without verification — use caution." Let user decide. | Never silently skip security |
| Large packages (500+ files) | Focus audit on: (1) entry points, (2) install/build scripts, (3) config files, (4) files with `eval`/`exec`/`spawn`/`system`. Skip docs, tests, assets. | Practical time management |
| `jq` or `curl` not installed | Scripts will fail with clear error. Inform user: "Required tool missing: install jq/curl first." | Documented dependency |
| `credentials.json` corrupt | Delete and re-register: `rm config/credentials.json && bash scripts/register.sh <name>` | Clean recovery |
## Installation Issues
### Skill not loading
**Checklist:**
- ✅ Did you restart your editor completely? (not just reload)
- ✅ Check frontmatter has `---` delimiters
- ✅ Verify directory name matches `name:` field in frontmatter
### "bash: scripts/gate.sh: No such file or directory"
**Solutions:**
- ✅ Use absolute paths: `bash ~/.claude/skills/agentaudit/scripts/gate.sh npm express`
- ✅ Or change to skill directory first: `cd ~/.claude/skills/agentaudit && bash scripts/gate.sh npm express`
- ✅ Verify you cloned the full repo, not just SKILL.md
### "jq: command not found" or "curl: command not found"
**Install required tools:**
**macOS:**
```bash
brew install jq # curl/bash pre-installed
```
**Ubuntu/Debian/WSL:**
```bash
sudo apt-get update && sudo apt-get install -y curl jq
```
**Fedora/RHEL:**
```bash
sudo dnf install -y curl jq
```
**Windows:**
Use [WSL](https://learn.microsoft.com/windows/wsl/install) or [Git Bash](https://git-scm.com/download/win)
## API Issues
### Authentication failures
If you get 401 errors:
1. Check if credentials exist:
```bash
cat config/credentials.json
```
2. Re-register if needed:
```bash
bash scripts/register.sh your-agent-name
```
3. Or set environment variable:
```bash
export AGENTAUDIT_API_KEY="your-key-here"
```
### Rate limiting (429 errors)
If you hit rate limits:
- Wait 2 minutes before retrying
- Save reports locally: `reports/<package>-<date>.json`
- Upload later when limits reset
### Network connectivity
If API is unreachable:
- Check internet connection
- Verify firewall settings
- Try manual curl: `curl -s https://agentaudit.dev/api/health`
- Consider using manual pre-checks before running gate script
## Verification Issues
### Hash mismatch errors
When integrity check fails:
1. Check if package version changed:
```bash
# Compare local version to audited version
```
2. If same version → likely tampered, DO NOT PROCEED
3. If different version → needs re-audit
### Unknown package (exit code 3)
This is NOT an error - it means no audit data exists yet.
**Required actions:**
1. Warn the user explicitly
2. Check red flags (age, downloads, author, typosquat)
3. Require explicit user confirmation
4. Trigger auto-audit if user confirms
See SKILL.md "Exit Code 3 — The Audit Gap" section for full guidance.
## Performance Issues
### Large packages taking too long
For packages with 500+ files:
**Focus on:**
1. Entry points (main, index files)
2. Install/build scripts
3. Config files
4. Files containing `eval`/`exec`/`spawn`/`system`
**Skip:**
- Documentation
- Tests
- Assets (images, fonts, etc.)
### Slow API responses
If API calls are slow:
- Check network latency
- Consider caching results locally
- Use integrity checks to avoid redundant full audits
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |