# Usage Examples - PQC Analyzer MCP Server

## Quick Start Examples

### Example 1: Analyze a Recent Commit

```
Analyze commit abc123 for PQC readiness
```

**Expected Output:**
```markdown
# PQC Readiness Analysis Report

## Commit Information
- Commit ID: abc123
- Repository: /Users/sucharitapaul/Documents/GitHub/cypto-agility

## Summary Statistics
- Total Algorithms Detected: 3
- PQC-Safe Algorithms: 2
- PQC-Unsafe Algorithms: 1
- Classical Algorithms: 1
- Hybrid Algorithms: 0

## PQC Readiness Score
- Score: 66.67%
- Quantum Risk Level: MEDIUM

## Detected Algorithms

### 1. RSA (CLASSICAL)
- File: `cryptoagility-lib/src/main/java/com/bobathon/cryptoagility/keygen/RSAKeyPairGenerator.java`
- Line: 15
- PQC Safe: ❌ No
- Context: `KeyPairGenerator kpg = KeyPairGenerator.getInstance("RSA", "BC");`

### 2. DILITHIUM (PQC)
- File: `cryptoagility-lib/src/main/java/com/bobathon/cryptoagility/keygen/DilithiumKeyPairGenerator.java`
- Line: 18
- PQC Safe: ✅ Yes
- Context: `KeyPairGenerator kpg = KeyPairGenerator.getInstance("Dilithium3", "BCPQC");`

### 3. FALCON (PQC)
- File: `cryptoagility-lib/src/main/java/com/bobathon/cryptoagility/keygen/FalconKeyPairGenerator.java`
- Line: 18
- PQC Safe: ✅ Yes
- Context: `KeyPairGenerator kpg = KeyPairGenerator.getInstance("Falcon-512", "BCPQC");`

## Recommendations

🟡 MEDIUM PRIORITY: PQC readiness is moderate. Plan migration strategy for remaining classical algorithms.

📊 Found 1 classical algorithm(s). Consider hybrid approach (RSA+Dilithium) for gradual migration.

✅ Excellent: 2 PQC algorithm(s) detected. Continue adopting NIST-standardized algorithms.
```

### Example 2: Get Algorithm Information

```
Get information about DILITHIUM algorithm
```

**Expected Output:**
```markdown
# Dilithium Algorithm Information

## Basic Information
- Type: Digital Signature
- Family: PQC
- NIST Status: NIST Standardized (FIPS 204)
- Security Level: NIST Level 2, 3, 5

## Technical Details
- Key Sizes: Dilithium2 (2420 bytes), Dilithium3 (3293 bytes), Dilithium5 (4595 bytes)
- Signature Size: 2420-4595 bytes
- Quantum Safe: ✅ Yes
- Recommended: ✅ Yes

## Use Cases
- TLS certificates
- Code signing
- Document signing
```

### Example 3: Compare Multiple Algorithms

```
Get information about all PQC algorithms
```

**Expected Output:**
```markdown
# Supported Cryptographic Algorithms

## Dilithium (PQC)
- Status: ✅ PQC-Safe
- NIST: NIST Standardized (FIPS 204)
- Recommended: Yes

## Falcon (PQC)
- Status: ✅ PQC-Safe
- NIST: NIST Standardized (FIPS 206)
- Recommended: Yes

## SPHINCS+ (PQC)
- Status: ✅ PQC-Safe
- NIST: NIST Standardized (FIPS 205)
- Recommended: Yes

## RSA (CLASSICAL)
- Status: ❌ Quantum-Vulnerable
- NIST: Classical Standard
- Recommended: No (Legacy)

## ECDSA (CLASSICAL)
- Status: ❌ Quantum-Vulnerable
- NIST: Classical Standard
- Recommended: No (Legacy)

## Hybrid (RSA+Dilithium) (HYBRID)
- Status: ✅ PQC-Safe
- NIST: Experimental
- Recommended: Yes
```

## Real-World Scenarios

### Scenario 1: Initial Codebase Assessment

**Goal:** Assess the current PQC readiness of your entire codebase.

**Steps:**
1. Get the latest commit ID:
   ```bash
   cd /path/to/your/repo
   git log -1 --format="%H"
   ```

2. Analyze the commit:
   ```
   Analyze commit <commit-id> for PQC readiness in /path/to/your/repo
   ```

3. Review the PQC Readiness Score and Quantum Risk Level

4. Follow the recommendations provided

### Scenario 2: Pre-Merge Review

**Goal:** Verify that a feature branch improves PQC readiness before merging.

**Steps:**
1. Get the merge commit or latest commit on the branch:
   ```bash
   git log feature-branch -1 --format="%H"
   ```

2. Analyze the commit:
   ```
   Analyze commit <commit-id> for PQC readiness
   ```

3. Compare with main branch baseline

4. Ensure PQC readiness percentage increases or stays high

### Scenario 3: Migration Planning

**Goal:** Plan the migration from classical to PQC algorithms.

**Steps:**
1. Analyze current state:
   ```
   Analyze commit HEAD for PQC readiness
   ```

2. Review detected classical algorithms

3. Get information about recommended PQC alternatives:
   ```
   Get information about DILITHIUM algorithm
   Get information about FALCON algorithm
   ```

4. Plan hybrid transition if needed:
   ```
   Get information about HYBRID algorithm
   ```

### Scenario 4: Compliance Audit

**Goal:** Generate a compliance report for quantum readiness.

**Steps:**
1. Analyze the production release commit:
   ```
   Analyze commit <release-tag> for PQC readiness
   ```

2. Document the results:
   - PQC Readiness Score
   - Quantum Risk Level
   - List of quantum-vulnerable algorithms
   - Remediation recommendations

3. Track progress over time by analyzing multiple commits

## Integration with CI/CD

### GitHub Actions Example

```yaml
name: PQC Readiness Check

on:
  pull_request:
    branches: [ main ]

jobs:
  pqc-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.12'
      
      - name: Install MCP SDK
        run: pip install mcp
      
      - name: Analyze PQC Readiness
        run: |
          # This would integrate with your MCP server
          # Example: Call the server to analyze the commit
          echo "Analyzing commit ${{ github.sha }}"
```

## Command Variations

### Analyze Specific Repository

```
Analyze commit abc123 for PQC readiness in /Users/sucharitapaul/Documents/GitHub/cypto-agility
```

### Analyze Current HEAD

```
Analyze the latest commit for PQC readiness
```

### Get Specific Algorithm Details

```
Tell me about RSA algorithm security
```

```
What is the quantum risk of ECDSA?
```

```
Compare DILITHIUM and FALCON algorithms
```

## Understanding the Results

### PQC Readiness Score Interpretation

| Score Range | Risk Level | Interpretation | Action Required |
|-------------|-----------|----------------|-----------------|
| 90-100% | LOW | Excellent quantum readiness | Maintain current practices |
| 70-89% | MEDIUM | Good progress, minor gaps | Plan remaining migrations |
| 40-69% | HIGH | Significant exposure | Prioritize PQC adoption |
| 0-39% | CRITICAL | Severe quantum risk | Immediate action needed |

### Algorithm Family Breakdown

- **Classical Count**: Number of quantum-vulnerable algorithms (RSA, ECDSA)
- **PQC Count**: Number of quantum-safe algorithms (Dilithium, Falcon, SPHINCS+)
- **Hybrid Count**: Number of transitional algorithms (RSA+Dilithium)

### Recommendations Priority

1. **🔴 CRITICAL**: Immediate security concerns
2. **🟡 MEDIUM**: Important but not urgent
3. **✅ GOOD**: Positive findings
4. **🎉 EXCELLENT**: Outstanding achievements

## Best Practices

### 1. Regular Monitoring

- Analyze every major commit or release
- Track PQC readiness trends over time
- Set minimum readiness thresholds for production

### 2. Gradual Migration

- Start with hybrid algorithms for compatibility
- Migrate critical systems first
- Test thoroughly before full PQC adoption

### 3. Documentation

- Document all algorithm choices
- Maintain a crypto inventory
- Track migration progress

### 4. Team Education

- Share PQC readiness reports with the team
- Explain quantum risks and mitigation strategies
- Provide training on PQC algorithms

## Troubleshooting

### No Algorithms Detected

**Possible Causes:**
- Commit doesn't modify crypto-related files
- Algorithm patterns not recognized
- Files are in unsupported languages

**Solution:**
- Verify the commit changes crypto code
- Check if file extensions are supported (.java, .py, .js, .ts, .go, .cpp, .c, .h)
- Review the algorithm patterns in server.py

### Incorrect Risk Level

**Possible Causes:**
- Hash algorithms counted as unsafe
- Hybrid algorithms not detected
- Custom algorithm implementations

**Solution:**
- Review the detected algorithms list
- Verify algorithm classification
- Update patterns if needed

### Git Errors

**Possible Causes:**
- Invalid commit ID
- Repository path incorrect
- Git not installed

**Solution:**
- Verify commit exists: `git log --oneline`
- Check repository path
- Install Git if missing

## Advanced Usage

### Batch Analysis

Analyze multiple commits:

```bash
# Get last 10 commits
git log -10 --format="%H" > commits.txt

# Analyze each (through IBM Bob)
for commit in $(cat commits.txt); do
  echo "Analyze commit $commit for PQC readiness"
done
```

### Trend Analysis

Track PQC readiness over time:

1. Analyze commits from different time periods
2. Compare readiness scores
3. Identify improvement trends
4. Adjust migration strategy accordingly

---

**Need more help?** Refer to README.md and INSTALLATION.md for additional information.