# Perseus:scan

> Use when starting a security assessment to map architecture, entry points, and attack surface (Phase 1 & 2)

- **Type:** Skill
- **Install:** `agentstack add skill-kaivyy-perseus-scan`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [kaivyy](https://agentstack.voostack.com/s/kaivyy)
- **Installs:** 0
- **Category:** [Security](https://agentstack.voostack.com/c/security)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [kaivyy](https://github.com/kaivyy)
- **Source:** https://github.com/kaivyy/perseus/tree/main/skills/perseus/scan

## Install

```sh
agentstack add skill-kaivyy-perseus-scan
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Perseus Scan (Phase 1 & 2)

## Overview

This skill executes the **Pre-Reconnaissance Methodology** of the Perseus framework. It maps the target's digital footprint, internal architecture, and attack surface to build a "Target Knowledge Graph".

**Goal:** Zero-blind-spot understanding of what exists, how it works, and where it can be attacked.

**Methodology:**
1.  **Discovery (Parallel):** Architecture, Entry Points, Security Patterns.
2.  **Surface Mapping (Parallel):** XSS Sinks, SSRF Sinks, Data Flows.
3.  **Synthesis:** Comprehensive Code Analysis Report.

## Incremental Scan Mode

For large codebases, use incremental scanning to only analyze changed files:

**Detection:** Check for `perseus.yaml` with incremental settings:
```yaml
incremental:
  enabled: true
  baseline: "main"  # or specific commit
```

**If incremental enabled:**
1. Run `git diff --name-only ...HEAD` to get changed files
2. Filter to include only code files (exclude tests, configs)
3. Focus analysis on changed files and their dependencies
4. Merge with previous cached results from `.perseus-cache/`

**Incremental Workflow:**
```bash
# Get changed files
git diff --name-only main...HEAD | grep -E '\.(js|ts|py|go|php|rb|java|rs|cs)$'

# If no changes, skip scan
# If changes exist, scan only those files + imports
```

## Execution Instructions

### Phase 1: Discovery (Run in Parallel)

Launch these 3 agents simultaneously using a single message with multiple `Task` tool calls:

1.  **Architecture Scanner:**
    *   "Map application structure, tech stack, frameworks, and critical components. Identify if web app, API, or microservices."
2.  **Entry Point Mapper:**
    *   "Find ALL network-accessible entry points (API routes, webhooks, public functions). Catalog API schema files (OpenAPI, GraphQL). Exclude local-only tools."
3.  **Security Pattern Hunter:**
    *   "Identify authentication flows, authorization mechanisms (RBAC/ABAC), session management, and security middleware. Map the security architecture."

### Phase 2: Surface Mapping (Run in Parallel)

*Wait for Phase 1 to complete.* Then launch these 3 agents simultaneously:

1.  **XSS/Injection Sink Hunter:**
    *   "Find dangerous sinks: `innerHTML`, `exec`, `system`, `eval`, SQL queries, file operations. Provide File:Line references."
2.  **SSRF/External Request Tracer:**
    *   "Identify server-side requests: HTTP clients (`fetch`, `axios`), URL fetchers, webhooks. Map user-controllable parameters."
3.  **Data Security Auditor:**
    *   "Trace sensitive data flows (PII, secrets, payments). Identify encryption and storage mechanisms."

### Phase 3: Reporting (Synthesis)

Synthesize all findings into `deliverables/code_analysis_deliverable.md`.

**Required Report Structure:**

1.  **Scope & Boundaries:** Define In-Scope (Network Reachable) vs Out-of-Scope (Local/CLI).
2.  **Executive Summary:** High-level security posture.
3.  **Architecture & Tech Stack:** Frameworks, patterns, components.
4.  **Authentication & Authorization:** Detailed analysis of auth flows and session handling.
5.  **Data Security:** Encryption, storage, and sensitive data handling.
6.  **Attack Surface:** Detailed list of In-Scope entry points.
7.  **Infrastructure:** Secrets management, config, logging.
8.  **Critical File Paths:** Categorized list for downstream agents.
9.  **XSS Sinks:** List of specific sinks and render contexts.
10. **SSRF Sinks:** List of specific outbound request sinks.

**Schema Collection:**
*   Create `outputs/schemas/` directory.
*   Copy all discovered schema files (OpenAPI, GraphQL, JSON Schema) there.

**Next Step:** Proceed to `perseus:audit` to analyze identified components for vulnerabilities.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [kaivyy](https://github.com/kaivyy)
- **Source:** [kaivyy/perseus](https://github.com/kaivyy/perseus)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-kaivyy-perseus-scan
- Seller: https://agentstack.voostack.com/s/kaivyy
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.