ctrlshiftleft/docs/AI_SECURITY_GUIDE.md

AI-powered toolkit for embedding QA and security testing into development workflows

# AI-Enhanced Security Analysis for ctrl.shift.left

This guide explains how to use the new AI-powered security analysis features in ctrl.shift.left to detect vulnerabilities, generate remediation suggestions, and improve your application's security posture.

## Overview

The AI-enhanced security analyzer extends the ctrl.shift.left toolkit with sophisticated analysis capabilities powered by OpenAI's language models. It provides:

1. **Deeper vulnerability detection** beyond simple pattern matching
2. **Contextual understanding** of your code's purpose and potential security implications
3. **Nuanced security scoring** based on vulnerability severity and context
4. **Detailed remediation suggestions** with ready-to-use code examples
5. **Comprehensive security reports** with insights from both pattern-based and AI analysis

## Setup

### Prerequisites

1. An OpenAI API key (obtainable from [OpenAI's platform](https://platform.openai.com/))
2. Node.js 14.0 or higher
3. The ctrl.shift.left toolkit installed

### Installation

The AI-enhanced security analyzer is included in the latest version of ctrl.shift.left. No additional installation is required beyond setting your OpenAI API key:

```bash
# Set your OpenAI API key as an environment variable
export OPENAI_API_KEY="your-api-key-here"

# Optional: Specify which model to use (defaults to gpt-4)
export OPENAI_MODEL="gpt-4"
```

For persistent configuration, you can add these to your shell profile or create a `.env` file in your project root:

```
OPENAI_API_KEY=your-api-key-here
OPENAI_MODEL=gpt-4
```

## Usage

### CLI Command

Use the AI-enhanced security analyzer via our new CLI command:

```bash
# Analyze a file with AI enhancement
./bin/ctrlshiftleft-ai analyze --ai src/components/PaymentForm.tsx

# Run the full security workflow with AI analysis
./bin/ctrlshiftleft-ai secure --ai src/components/LoginForm.jsx
```

### Options

The AI-enhanced analyzer supports the following options:

| Option | Description |
|--------|-------------|
| `--ai` | Enable AI-powered analysis (requires OPENAI_API_KEY) |
| `--output=<file>` | Specify an output file for the report |

### VS Code Extension Integration

The AI analyzer is also integrated with the ctrl.shift.left VS Code extension. To use it:

1. Ensure your OPENAI_API_KEY is set in your environment
2. Right-click on a file in VS Code
3. Select "Ctrl+Shift+Left: AI Security Analysis"

## Understanding the Output

### Security Score

The AI analyzer provides a security score from 0-100 based on:

- Number of detected vulnerabilities
- Severity of each vulnerability (Critical, High, Medium, Low, Info)
- Code complexity and attack surface

### Report Structure

The AI-enhanced security report includes:

1. **Summary**: Overall security score and key findings
2. **Detailed Findings**: Vulnerabilities grouped by severity
3. **Remediation Suggestions**: Code examples for fixing each issue
4. **Next Steps**: Recommendations for improving security

## Examples

### Pattern vs. AI Analysis

Compare traditional pattern matching with AI-enhanced analysis:

**Pattern-Based Detection**:
```
Medium Severity
- Client-side Storage of Sensitive Data
- Line 42: sessionStorage.setItem('token', authToken);
- Remediation: Use secure storage mechanisms or encrypted tokens
```

**AI-Enhanced Detection**:
```
Medium Severity
- Insecure Token Storage in Client-Side Storage
- Lines: 42-47
- Description: Authentication tokens stored in sessionStorage can be accessed by any script running on the same origin, making them vulnerable to XSS attacks.
- Remediation: Use HTTP-only cookies for token storage or implement a token refresh mechanism.
- Code Example:
  // Instead of:
  sessionStorage.setItem('token', authToken);
  
  // Use HTTP-only cookies (server-side):
  res.cookie('auth', token, { 
    httpOnly: true,
    secure: true,
    sameSite: 'strict'
  });
```

## Advanced Configuration

### Customizing Analysis

You can customize the AI analyzer by modifying:

1. **Model Selection**: Set the `OPENAI_MODEL` environment variable to use different models (e.g., "gpt-3.5-turbo" for faster but less detailed analysis)
2. **Output Format**: Use the `--format=json` option for programmatic consumption

### Integration with CI/CD

Add AI-powered security analysis to your CI/CD pipeline:

```yaml
# GitHub Actions example
security-analysis:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v3
    - name: Set up Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '16'
    - name: Install dependencies
      run: npm ci
    - name: Run AI security analysis
      env:
        OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
      run: ./bin/ctrlshiftleft-ai analyze --ai src/
    # Additional steps to fail the build on critical issues, etc.
```

## Troubleshooting

### Common Issues

1. **API Key Not Found**: Ensure your OPENAI_API_KEY is properly set
2. **Rate Limiting**: OpenAI has rate limits that may affect analysis of large codebases
3. **Model Selection**: Consider using "gpt-3.5-turbo" for faster analysis if gpt-4 is too slow

### Fallback Behavior

If AI analysis fails for any reason, the system will automatically fall back to pattern-based analysis, ensuring you always get security feedback.

## Best Practices

1. **Start Small**: Begin by analyzing your most security-critical components
2. **Review AI Suggestions**: While powerful, AI suggestions should be reviewed by a developer
3. **Combine with Testing**: Use the generated tests to verify that security fixes actually work
4. **Regular Scans**: Incorporate AI analysis into your regular development workflow

## Performance Considerations

The AI-enhanced analyzer processes code files through the OpenAI API, which has some limitations:

1. **File Size**: Very large files may need to be truncated
2. **Analysis Time**: AI analysis is slower than pattern matching (typically 5-15 seconds per file)
3. **Cost**: Using the OpenAI API incurs costs based on your usage

For large codebases, consider batching analysis or focusing on security-critical components.

---

By leveraging both pattern-based and AI-powered analysis, ctrl.shift.left provides comprehensive security insights that help you shift security left in your development workflow.