{"id":44412351,"url":"https://github.com/kaivyy/perseus","last_synced_at":"2026-02-15T10:01:27.080Z","repository":{"id":337259196,"uuid":"1152840229","full_name":"kaivyy/perseus","owner":"kaivyy","description":"AI-powered security assessment for your codebase. Multi-language (JS, Go, Python, Rust, Java, PHP, Ruby, C#). Works with Claude Code, Codex, OpenCode.","archived":false,"fork":false,"pushed_at":"2026-02-12T05:38:02.000Z","size":1505,"stargazers_count":16,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-12T15:38:38.132Z","etag":null,"topics":["ai-security","claude","claude-code","code-review","cybersecurity","devsecops","penetration-testing","security","security-audit","static-analysis","vulnerability-scanner"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kaivyy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-08T14:17:36.000Z","updated_at":"2026-02-12T05:35:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kaivyy/perseus","commit_stats":null,"previous_names":["kaivyy/perseus"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/kaivyy/perseus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaivyy%2Fperseus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaivyy%2Fperseus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaivyy%2Fperseus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaivyy%2Fperseus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kaivyy","download_url":"https://codeload.github.com/kaivyy/perseus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaivyy%2Fperseus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29399429,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-13T06:24:03.484Z","status":"ssl_error","status_checked_at":"2026-02-13T06:23:12.830Z","response_time":78,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-security","claude","claude-code","code-review","cybersecurity","devsecops","penetration-testing","security","security-audit","static-analysis","vulnerability-scanner"],"created_at":"2026-02-12T07:46:30.711Z","updated_at":"2026-02-14T09:01:34.651Z","avatar_url":"https://github.com/kaivyy.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Perseus Security Skills for Claude Code\n\n![Perseus Plugin](docs/perseus.png)\n\nPerseus is a comprehensive suite of interactive security assessment skills for Claude Code. It transforms Claude into an autonomous penetration testing partner for **your own codebase**, capable of performing everything from initial reconnaissance to deep-dive vulnerability research and executive reporting.\n\n\u003e **Defensive Security Testing:** Perseus analyzes your own code to find vulnerabilities before attackers do. This is equivalent to running a security linter or static analyzer.\n\n## Features\n\n### Multi-Language Support (8 Languages)\n| Language | Frameworks |\n|----------|------------|\n| JavaScript/TypeScript | Express, Fastify, Next.js, Nest.js, Hono, Bun |\n| Go | Gin, Echo, Fiber, Chi |\n| PHP | Laravel, Symfony, Slim, Lumen |\n| Python | FastAPI, Django, Flask, Starlette |\n| Rust | Actix-web, Axum, Rocket, Warp |\n| Java | Spring Boot, Quarkus, Micronaut |\n| Ruby | Rails, Sinatra, Grape |\n| C# | ASP.NET Core, Minimal APIs |\n\n### Smart Auto-Detection\nPerseus automatically detects your project's:\n- **Language \u0026 Framework** (Next.js, Django, Spring, etc.)\n- **Database** (PostgreSQL, MongoDB, Redis, etc.)\n- **Infrastructure** (Docker, Kubernetes, AWS/GCP/Azure)\n- **CI/CD** (GitHub Actions, GitLab CI, Jenkins)\n- **AI/LLM** (OpenAI, Anthropic, LangChain)\n\n### Extended Coverage\n- **API Security**: REST, GraphQL, WebSocket, gRPC, OAuth, Cache poisoning\n- **Injection**: SQL, NoSQL, Command, SSTI, LDAP, XPath, Log4j\n- **Infrastructure**: Docker, CI/CD, Cloud (AWS/GCP/Azure), Kubernetes\n- **AI Security**: Prompt injection, RAG security, tool use validation\n- **Client-Side**: React, Next.js SSR, Vue, Angular, Server Actions\n\n---\n\n## Installation\n\n### Claude Code\n```\n/plugin install https://github.com/kaivyy/perseus\n```\n\nThat's it! Everything is automatic:\n- Skills and commands auto-discovered\n- Hooks auto-registered\n- Context injected on session start\n\n### Codex\n```bash\ngit clone https://github.com/kaivyy/perseus.git ~/.codex/perseus\nmkdir -p ~/.agents/skills\nln -sf ~/.codex/perseus/skills ~/.agents/skills/perseus\n```\n\n### OpenCode\n```bash\ngit clone https://github.com/kaivyy/perseus.git ~/.config/opencode/perseus \u0026\u0026 \\\n  mkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills \u0026\u0026 \\\n  ln -sf ~/.config/opencode/perseus/.opencode/plugins/perseus.js ~/.config/opencode/plugins/perseus.js \u0026\u0026 \\\n  ln -sf ~/.config/opencode/perseus/skills ~/.config/opencode/skills/perseus\n```\n\n### Uninstall\n```\n/plugin uninstall perseus\n```\n\n---\n\n## Quick Start\n\n```bash\n# Full automated assessment (with smart auto-detect)\n/start\n\n# Or run phases individually\n/scan        # Phase 1: Reconnaissance\n/audit       # Phase 2: Vulnerability Analysis\n/exploit     # Phase 3: PoC Verification\n/report      # Phase 4: Executive Report\n\n# Run all specialists\n/specialist\n```\n\n---\n\n## Engagement Modes\n\nPerseus uses explicit verification modes during assessment:\n\n| Mode | Environment | Verification Style |\n|------|-------------|--------------------|\n| `PRODUCTION_SAFE` | Live production | Passive-first checks + minimal non-disruptive validation |\n| `STAGING_ACTIVE` | Staging/pre-production | Active verification with strict throttling |\n| `LAB_FULL` | Isolated lab | Broad dynamic verification |\n| `LAB_RED_TEAM` | Dedicated security lab | Controlled adversarial chain simulation with kill-switches |\n\nDefault mode is `PRODUCTION_SAFE` when environment is unclear.\n\n---\n\n## Core Assessment Phases\n\nPerseus follows a structured 4-phase methodology:\n\n### Phase 1: Scan (Reconnaissance)\nMaps architecture, entry points, dependencies, and attack surface.\n\n| Command | Agents | Output |\n|---------|--------|--------|\n| `/scan` | 13 parallel agents | `deliverables/code_analysis_deliverable.md` |\n\n**Coverage:**\n- Architecture \u0026 Tech Stack (auto-detect 8 languages)\n- Entry Points (API, GraphQL, WebSocket, gRPC)\n- Dependencies \u0026 CVEs\n- Hardcoded Secrets\n- Security Patterns (Auth, Authz)\n- Injection Sinks \u0026 XSS Sinks\n- SSRF \u0026 Data Flows\n- Crypto Usage\n- Security Headers \u0026 Config\n\n### Phase 2: Audit (Vulnerability Analysis)\nDeep white-box analysis using Negative Analysis Loop (Source → Flow → Sink → Defense → Verdict).\n\n| Command | Agents | Output |\n|---------|--------|--------|\n| `/audit` | 14 parallel agents (3 waves) | Multiple `*_analysis.md` files |\n\n**Wave 1:** SQL Injection, Command Injection, XSS, Auth, Authz\n**Wave 2:** SSRF, Template Injection, Deserialization, Path Traversal, XXE\n**Wave 3:** JWT, Crypto, Race Conditions, Business Logic\n\n### Phase 3: Exploit (Verification)\nVerify findings with mode-aware safe Proof-of-Concept payloads.\n\n| Command | Agents | Output |\n|---------|--------|--------|\n| `/exploit` | Mode-aware verifiers | `deliverables/exploitation_report.md` |\n\n**Safe Payloads Only:**\n- SQL: `SLEEP(5)`, `AND 1=1`\n- Command: `sleep 5`, `whoami`\n- XSS: `alert(1)`, `alert(document.domain)`\n- SSTI: `{{7*7}}` → `49`\n\n### Phase 4: Report (Executive Summary)\nSynthesize all findings into professional security report.\n\n| Command | Output |\n|---------|--------|\n| `/report` | `deliverables/SECURITY_REPORT.md` |\n\n**Report Includes:**\n- Executive Summary \u0026 Risk Overview\n- Engagement mode and verification coverage\n- Technologies Analyzed (language, framework, infrastructure)\n- Verified Exploits with PoC\n- Infrastructure Security (Docker, CI/CD, Cloud, K8s)\n- AI/LLM Security Findings\n- Supply Chain Summary\n- Language-specific Remediation Guidance\n- Strategic Recommendations\n\n---\n\n## Specialist Deep-Dive Skills\n\nPerseus provides 8 enhanced specialist skills with multi-language support:\n\n| Command | Skill | Coverage |\n|---------|-------|----------|\n| `/perseus:api` | API Security | OWASP API Top 10, GraphQL, WebSocket, OAuth, Cache, gRPC |\n| `/perseus:injection` | Advanced Injection | NoSQL, LDAP, XPath, SSTI, Command, Log4j, Expression Language |\n| `/perseus:crypto` | Cryptography | JWT (8 languages), Hashing, Encryption, Key Management |\n| `/perseus:supply-chain` | Supply Chain | CVEs (8 package managers), Typosquatting, Dependency Confusion |\n| `/perseus:file` | File Security | Path Traversal, Upload Bypass, XXE, Zip Slip (8 languages) |\n| `/perseus:logic` | Business Logic | Race Conditions, **AI/LLM Security**, Price Manipulation |\n| `/perseus:client` | Client-Side | React, Next.js SSR, Server Actions, Vue, Angular, Svelte |\n| `/perseus:config` | Configuration | **Docker, CI/CD, Cloud (AWS/GCP/Azure), Kubernetes** |\n| `/specialist` | **All Above** | Runs all 8 specialists in parallel |\n\n---\n\n## Command Reference\n\n### Short Commands (Aliases)\n| Command | Description |\n|---------|-------------|\n| `/start` | Full automated assessment with smart auto-detect |\n| `/scan` | Phase 1: Reconnaissance |\n| `/audit` | Phase 2: Vulnerability Analysis |\n| `/exploit` | Phase 3: PoC Verification |\n| `/report` | Phase 4: Executive Report |\n| `/specialist` | Run all 8 specialist skills |\n\n### Full Commands\n| Command | Description |\n|---------|-------------|\n| `/perseus:start` | Full automated assessment |\n| `/perseus:scan` | Reconnaissance |\n| `/perseus:audit` | Vulnerability Analysis |\n| `/perseus:exploit` | PoC Verification |\n| `/perseus:report` | Executive Report |\n| `/perseus:specialist` | All specialists |\n| `/perseus:api` | API Security |\n| `/perseus:injection` | Advanced Injection |\n| `/perseus:crypto` | Cryptography |\n| `/perseus:supply-chain` | Supply Chain |\n| `/perseus:file` | File Security |\n| `/perseus:logic` | Business Logic + AI Security |\n| `/perseus:client` | Client-Side |\n| `/perseus:config` | Configuration + Infrastructure |\n\n---\n\n## Output Structure\n\nAfter a full assessment, the `deliverables/` directory contains:\n\n```\ndeliverables/\n├── engagement_profile.md          # Mode, scope, limits, kill-switch thresholds\n├── code_analysis_deliverable.md    # Scan results (multi-language)\n├── sql_injection_analysis.md       # Audit reports\n├── command_injection_analysis.md\n├── xss_analysis.md\n├── auth_analysis.md\n├── authz_analysis.md\n├── ssrf_analysis.md\n├── template_injection_analysis.md\n├── deserialization_analysis.md\n├── path_traversal_analysis.md\n├── xxe_analysis.md\n├── jwt_analysis.md\n├── crypto_analysis.md\n├── race_condition_analysis.md\n├── business_logic_analysis.md\n├── api_security_analysis.md        # Specialist reports\n├── injection_deep_analysis.md\n├── crypto_security_analysis.md\n├── supply_chain_analysis.md\n├── file_security_analysis.md\n├── client_side_analysis.md\n├── config_security_analysis.md     # Includes Docker/CI/K8s\n├── verification_scope.md           # Verification boundaries and approved test window\n├── exploitation_report.md          # Verified exploits\n└── SECURITY_REPORT.md              # Final executive report\n```\n\n---\n\n## Project Structure\n\n```\nperseus/\n├── commands/                    # Command definitions\n│   ├── scan.md                  # Short aliases\n│   ├── audit.md\n│   ├── exploit.md\n│   ├── report.md\n│   ├── start.md\n│   ├── specialist.md\n│   ├── perseus:scan.md          # Full commands\n│   ├── perseus:audit.md\n│   ├── perseus:exploit.md\n│   ├── perseus:report.md\n│   ├── perseus:start.md\n│   ├── perseus:specialist.md\n│   ├── perseus:api.md\n│   ├── perseus:injection.md\n│   ├── perseus:crypto.md\n│   ├── perseus:supply-chain.md\n│   ├── perseus:file.md\n│   ├── perseus:logic.md\n│   ├── perseus:client.md\n│   └── perseus:config.md\n├── skills/\n│   └── perseus/\n│       ├── scan/SKILL.md        # Core skills\n│       ├── audit/SKILL.md\n│       ├── exploit/SKILL.md\n│       ├── report/SKILL.md\n│       ├── start/SKILL.md\n│       ├── using-perseus/SKILL.md\n│       └── specialists/         # Specialist skills\n│           ├── api/SKILL.md\n│           ├── injection/SKILL.md\n│           ├── crypto/SKILL.md\n│           ├── supply-chain/SKILL.md\n│           ├── file-security/SKILL.md\n│           ├── logic/SKILL.md\n│           ├── client/SKILL.md\n│           ├── config/SKILL.md\n│           └── all/SKILL.md\n├── scripts/\n│   ├── post-install.sh          # Auto symlink + hook patch\n│   └── uninstall.sh\n├── hooks/\n│   ├── hooks.json\n│   └── session-start.sh\n├── tests/\n│   ├── README.md\n│   ├── run-tests.sh\n│   └── validate-structure.cjs\n├── LICENSE\n└── README.md\n```\n\n---\n\n## Running Tests\n\n```bash\n./tests/run-tests.sh\n```\n\nValidates:\n- Metadata files (plugin.json, manifest.json)\n- Core skills (6 skills)\n- Specialist skills (9 skills)\n- Short commands (6 commands)\n- Perseus commands (14 commands)\n\n---\n\n## Safety \u0026 Ethics\n\nPerseus is designed for **defensive security testing only**:\n\n- All analysis is performed on **your own codebase**\n- Safe payloads only (no destructive operations)\n- `PRODUCTION_SAFE` is the default mode\n- Aggressive simulation is restricted to staging/lab modes\n- `LAB_RED_TEAM` requires isolated environment and non-production data\n- Kill-switch can stop active tests with `ABORTED-SAFETY`\n- No data exfiltration\n- Evidence-based reporting (no hallucinations)\n- Equivalent to running security linters or SAST tools\n\n---\n\n## Troubleshooting\n\n### Hook Blocking Issue\n\n**Problem:** Perseus scan/audit fails with error like:\n```\nError: PreToolUse:Write hook error: ⚠️ Security Warning: dangerouslySetInnerHTML...\n```\n\n**Cause:** The `security-guidance` plugin blocks files containing security-related keywords, even in documentation.\n\n**Solution 1: Automatic (Recommended)**\n\nRestart your Claude Code session. Perseus auto-patches the security hook on session start:\n```bash\n/clear\n# Then run Perseus again\n/scan\n```\n\n**Solution 2: Manual Patch**\n\nIf auto-patch doesn't work, run manually:\n```bash\n~/.claude/plugins/perseus/scripts/post-install.sh\n```\n\n**Solution 3: Patch All Hook Locations**\n\nThe security hook may exist in multiple locations (cache + marketplaces). Patch all:\n```bash\n# Find all hook locations\nfind ~/.claude -name \"security_reminder_hook.py\"\n\n# The script patches all locations automatically\nbash ~/.claude/plugins/perseus/hooks/session-start.sh\n```\n\n**Solution 4: Disable Security Hook (Temporary)**\n\n```bash\nexport ENABLE_SECURITY_REMINDER=0\n```\n\n### Deliverables Not Created\n\n**Problem:** `deliverables/` folder is empty after scan.\n\n**Cause:** Hook blocked file writing (see above).\n\n**Solution:** Fix the hook issue, then run `/scan` again.\n\n### Skills Not Found\n\n**Problem:** `/scan` or `/audit` says skill not found.\n\n**Solution:** Run the post-install script:\n```bash\n~/.claude/plugins/perseus/scripts/post-install.sh\n```\n\nThis creates all necessary symlinks automatically.\n\n### Session Start Hook Not Running\n\n**Problem:** Auto-patch doesn't happen on session start.\n\n**Solution:** Verify hooks.json exists and is valid:\n```bash\ncat ~/.claude/plugins/perseus/hooks/hooks.json\n```\n\nShould contain `SessionStart` configuration.\n\n---\n\n## Changelog\n\n### v2.2.1 (2026-02)\n- Added engagement modes: `PRODUCTION_SAFE`, `STAGING_ACTIVE`, `LAB_FULL`, `LAB_RED_TEAM`\n- Added mode-aware verification and specialist safety gates\n- Added kill-switch behavior and `ABORTED-SAFETY` outcomes\n- Added new deliverables: `engagement_profile.md`, `verification_scope.md`\n- Improved reporting with verification coverage and context-aware risk weighting\n\n### v2.0.0 (2026-02)\n- **Multi-Language Support**: Added support for 8 languages (JS, Go, PHP, Python, Rust, Java, Ruby, C#)\n- **Smart Auto-Detect**: `/start` now auto-detects language, framework, and infrastructure\n- **Infrastructure Security**: Added Docker, CI/CD, Cloud (AWS/GCP/Azure), Kubernetes analysis\n- **AI/LLM Security**: Added prompt injection, RAG security, tool use validation\n- **Enhanced Specialists**: All 8 specialists now support multiple languages\n- **Improved Report**: Added infrastructure, AI, and supply chain sections\n\n### v1.0.0 (2026-01)\n- Initial release with core phases and specialists\n\n---\n\n## Documentation\n\n| Platform | Guide |\n|----------|-------|\n| Claude Code | [docs/README.claude.md](docs/README.claude.md) |\n| Codex | [docs/README.codex.md](docs/README.codex.md) |\n| OpenCode | [docs/README.opencode.md](docs/README.opencode.md) |\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaivyy%2Fperseus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkaivyy%2Fperseus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaivyy%2Fperseus/lists"}