# Snow CLI Usage Documentation - Vulnerability Hunting Mode

Welcome to Snow CLI! Agentic coding in your terminal.

## What is Vulnerability Hunting Mode

Vulnerability Hunting Mode is a professional security analysis agent mode in Snow CLI, focused on discovering and verifying security vulnerabilities in your codebase. Unlike normal conversation mode, this mode follows a strict security analysis workflow, providing systematic vulnerability detection, evidence collection, verification script generation, and detailed reports.

## Why Use Vulnerability Hunting Mode

Security vulnerabilities can lead to serious consequences during software development. Vulnerability Hunting Mode provides professional security analysis capabilities:

- Systematic vulnerability detection process covering multiple vulnerability types
- Evidence-based analysis to avoid false positives
- Generate executable verification scripts for each vulnerability
- Detailed fix recommendations and priority ranking
- Interactive communication ensuring accurate analysis scope
- Focus on specific modules avoiding superficial analysis

## Enable Vulnerability Hunting Mode

### Toggle Using Command

Type in Snow CLI conversation interface:

```
/vulnerability-hunting
```

System will display mode toggle prompt, type command again to disable the mode.

### Mode Status

- Mode status is saved in localStorage
- Maintains last status after application restart
- Can switch back to normal mode anytime

## Core Principles

Vulnerability Hunting Mode follows these core principles:

### 1. User Query First

AI prioritizes responding to your actual questions and needs, won't arbitrarily analyze entire codebase without request.

### 2. Language Adaptation

AI always responds and generates reports in the same language as yours.

### 3. Interactive Communication

AI frequently uses interactive Q&A to:
- Clarify ambiguous requirements
- Confirm analysis scope
- Ask about specific test scenarios
- Verify discovered issues
- Get permission for code modifications

### 4. Evidence-Based Analysis

All vulnerability reports must have specific code evidence, AI won't make guesses or assumptions.

### 5. Focused Scope

Only analyze specific modules or components each time, not entire codebase at once.

### 6. Verification Required

Every vulnerability must have verification script or proof-of-concept code.

### 7. Read-Only Analysis

Unless you explicitly request, AI won't modify source code, only generates reports and recommendations.

## Complete Workflow

Vulnerability Hunting Mode follows a strict 5-phase workflow:

### Phase 1: Scope Definition (Mandatory)

**Objective**: Clearly define specific area to analyze.

**Process**:

1. **If you didn't specify module**:
   - AI explores codebase structure
   - Lists major modules and components
   - Asks which specific area you want to analyze

2. **If you specified vague area**:
   - AI breaks it down into smaller sub-components
   - Asks if you focus on all parts or specific parts

3. **Confirm before starting analysis**:
   - Prioritize which vulnerability categories (logic errors vs security issues)
   - Expected analysis depth
   - Specific concerns or known issues

**Scope Document Example**:


## Use Case Examples

### Scenario 1: Analyze Specific Module

```
You: Enter vulnerability hunting mode, analyze authentication module

AI: Okay, I've switched to vulnerability hunting mode. Let me explore the authentication module structure...

I found these authentication-related components:
1. Login flow (login.ts, auth.ts)
2. Session management (session.ts, middleware.ts)
3. Password reset (resetPassword.ts)
4. Token handling (jwt.ts, tokenService.ts)

Which specific area do you want to analyze first? Or should I check all components?

You: First check JWT token handling

AI: Understood. Before starting analysis, I want to confirm:

Do you want me to prioritize:
1. Logic errors (null checks, boundary cases, race conditions)
2. Security issues (injection, auth bypass, data leaks)
3. Check both

You: Check both

AI: Okay, I'll comprehensively analyze JWT token handling module...

[Performing analysis...]

I found the following issues:
1. [Critical] JWT signature verification missing
2. [High] Token expiry check logic error
3. [Medium] Token refresh mechanism missing

I've created verification scripts. Want to see detailed report?
```

### Scenario 2: Verify Known Issue

```
You: I suspect user input handling has SQL injection, help me verify

AI: Okay, let me locate code related to user input handling...

I found these places processing user input:
- src/controllers/userController.ts:searchUser()
- src/controllers/productController.ts:search()
- src/services/queryBuilder.ts:buildQuery()

Are these all your concerns? Or a specific function?

You: Mainly the searchUser function

AI: Understood. I'll focus on analyzing SQL injection risk in that function...

[After analysis...]

Confirmed SQL injection vulnerability! Details:
- Location: src/controllers/userController.ts:42
- Issue: Direct concatenation of user input into SQL query
- Severity: Critical

I've created verification script: .snow/vulnerability-hunting/scripts/verify-sql-injection.sh

Running this script can actually trigger the vulnerability. Need me to generate detailed report and fix recommendations?
```

### Scenario 3: Generate Security Report

You: Generate security analysis report for entire API module

AI: Okay, the API module is large. Let me list main sub-modules:

1. User API (/api/users/*)
2. Product API (/api/products/*)
3. Order API (/api/orders/*)
4. Auth API (/api/auth/*)
5. Admin API (/api/admin/*)

Since there are many modules, recommend analyzing in batches. Which one to start with?
Or should I do a quick high-level scan to find most obvious issues?

You: First do quick scan, find serious issues

AI: Understood, I'll conduct quick security scan focusing on critical vulnerabilities...

[After scanning...]

Quick scan complete, found following serious issues:

1. [Critical] User API: SQL injection (3 places)
2. [Critical] Auth API: JWT signature verification missing
3. [Critical] Admin API: Missing permission checks
4. [High] Order API: Race condition may cause duplicate charging

Recommend fixing these serious issues first. Need me to create detailed report and verification script for each issue?

## File Structure

All files generated by Vulnerability Hunting Mode are stored in project's `.snow/vulnerability-hunting/` directory:

```text
.snow/
└── vulnerability-hunting/
    ├── docs/                           # Analysis report directory
    │   ├── auth-module.md             # Authentication module report
    │   ├── api-security-scan.md       # API security scan report
    │   └── payment-module.md          # Payment module report
    └── scripts/                        # Verification script directory
        ├── verify-jwt-bypass.js       # JWT bypass verification
        ├── verify-sql-injection.sh    # SQL injection verification
        ├── verify-race-condition.js   # Race condition verification
        └── verify-auth-bypass.py      # Auth bypass verification
```


### Report Naming Convention

- Use lowercase letters and hyphens
- Format: `[module-name]-[report-type].md`
- Examples: `auth-module.md`, `api-security-scan.md`

### Script Naming Convention

- Use lowercase letters and hyphens
- Format: `verify-[vulnerability-type].[extension]`
- Examples: `verify-sql-injection.sh`, `verify-null-pointer.js`

## Best Practices

### 1. Define Clear Analysis Scope

Don't request analyzing entire codebase, instead:
- Specify specific modules or components
- Clarify focused vulnerability types
- Provide known risk points

### 2. Timely Communication

AI will frequently ask to confirm details, please:
- Answer AI's questions to clarify requirements
- Provide additional context information
- Explain specific security concerns

### 3. Verify Findings

For issues AI discovers:
- Run provided verification scripts
- Confirm in test environment
- Evaluate actual impact

### 4. Prioritize Fixes

Based on priorities in report:
- Fix critical vulnerabilities immediately
- Sort other issues by priority
- Document fix process

### 5. Continuous Improvement

After fixing vulnerabilities:
- Request AI to re-verify
- Add security tests
- Update security checklist

## Limitations and Considerations

### 1. Analysis Scope

- Only analyze specific module each time, not entire codebase
- Need to clearly specify analysis scope
- Large projects recommend multiple analyses

### 2. Verification Scripts

- Scripts should run in isolated environment
- Some scripts may require specific test environment
- Read script content carefully before running

### 3. Read-Only Mode

- Doesn't modify source code by default
- Only generates reports and fix recommendations
- Must explicitly request when needing code fixes

### 4. False Positive Possibility

- AI analysis may produce false positives
- Always verify discovered issues
- Combine with manual review

### 5. Coverage

- Cannot guarantee finding all vulnerabilities
- Focuses on common and serious security issues
- Recommend combining with other security tools

## Common Issues

**Q: What's difference between Vulnerability Hunting Mode and normal mode?**

A: Vulnerability Hunting Mode is specialized security analysis agent, follows strict 5-phase workflow, generates detailed reports and verification scripts. Normal mode is more general, suitable for daily development tasks.

**Q: How long does analyzing a module take?**

A: Depends on module size and complexity. Small modules (few hundred lines) may take several minutes, medium modules (several thousand lines) may take 10-30 minutes, large modules recommend splitting analysis.

**Q: Are verification scripts safe?**

A: Verification scripts are designed to run safely, won't cause permanent damage. But recommend running in isolated test environment, don't execute in production environment.

**Q: Can AI automatically fix vulnerabilities?**

A: Not by default. AI only provides fix recommendations. If you need automatic fixes, must explicitly request, and AI will seek your confirmation first.

**Q: How to view previous analysis reports?**

A: All reports are saved in `.snow/vulnerability-hunting/docs/` directory, can view anytime.

**Q: Can I customize analysis categories?**

A: Yes. AI will ask before starting which categories you focus on. You can specify only checking logic errors, only checking security issues, or checking both.

**Q: What programming languages does Vulnerability Hunting Mode support?**

A: Supports common programming languages including JavaScript/TypeScript, Python, Java, Go, Rust, C#, etc. Analysis quality depends on codebase indexing status.

**Q: Will discovered vulnerabilities be automatically reported to team?**

A: No. All reports only stored locally. You need to manually share reports or integrate into your security workflow.

**Q: Can reports be exported to other formats?**

A: Reports are generated in Markdown format, can easily convert to PDF, HTML, or other formats. You can also request AI to generate reports in specific format.

**Q: How to use with CI/CD?**

A: Can run verification scripts in CI/CD process to detect if known vulnerabilities are fixed. But complete analysis recommend manual triggering as it requires interactive communication.

## Related Features

- [Command Panel Guide](./09.0.Command%20Panel%20Guide.md) - Learn about `/vulnerability-hunting` and other commands
- [Sensitive Commands Configuration](./06.Sensitive%20Commands%20Configuration.md) - Configure dangerous commands requiring confirmation
- [Codebase Setup](./04.Codebase%20Setup.md) - Enable codebase indexing to improve analysis effectiveness