# Security Testing Guide

> Sprint: SPRINT_0352_0001_0001_security_testing_framework
> Task: SEC-0352-010

This guide describes the security testing framework used in StellaOps, aligned with OWASP Top 10 categories.

## Overview

The security testing framework provides automated tests for common security vulnerabilities organized by OWASP category:

| OWASP Category | Directory | Status |
|----------------|-----------|--------|
| A01: Broken Access Control | `A01_BrokenAccessControl/` | ✓ Implemented |
| A02: Cryptographic Failures | `A02_CryptographicFailures/` | ✓ Implemented |
| A03: Injection | `A03_Injection/` | ✓ Implemented |
| A05: Security Misconfiguration | `A05_SecurityMisconfiguration/` | ✓ Implemented |
| A07: Authentication Failures | `A07_AuthenticationFailures/` | ✓ Implemented |
| A08: Software/Data Integrity | `A08_SoftwareDataIntegrity/` | ✓ Implemented |
| A10: SSRF | `A10_SSRF/` | ✓ Implemented |

## Directory Structure

```
tests/
└── security/
    ├── README.md
    └── StellaOps.Security.Tests/
        ├── Infrastructure/
        │   ├── SecurityTestBase.cs
        │   ├── MaliciousPayloads.cs
        │   └── SecurityAssertions.cs
        ├── A01_BrokenAccessControl/
        ├── A02_CryptographicFailures/
        ├── A03_Injection/
        ├── A05_SecurityMisconfiguration/
        ├── A07_AuthenticationFailures/
        ├── A08_SoftwareDataIntegrity/
        └── A10_SSRF/
```

## Running Security Tests

### Local Execution

```bash
# Run all security tests
cd tests/security/StellaOps.Security.Tests
dotnet test --filter "Category=Security"

# Run specific OWASP category
dotnet test --filter "OWASP=A01"

# Run with detailed output
dotnet test --filter "Category=Security" --verbosity detailed
```

### CI Integration

Security tests run automatically on:
- All pull requests to `main` or `develop`
- Scheduled nightly builds

Results are uploaded as artifacts and any failures block the PR.

## Test Categories

### A01: Broken Access Control

Tests for authorization bypass vulnerabilities:
- Tenant isolation violations
- RBAC enforcement
- Privilege escalation
- IDOR (Insecure Direct Object References)

### A02: Cryptographic Failures

Tests for cryptographic weaknesses:
- Key material exposure in logs
- Weak algorithm usage
- TLS configuration
- Secure random generation

### A03: Injection

Tests for injection vulnerabilities:
- SQL injection (parameterization)
- Command injection
- ORM injection
- Path traversal

### A05: Security Misconfiguration

Tests for configuration errors:
- Debug mode in production
- Error detail leakage
- Security headers
- CORS configuration

### A07: Authentication Failures

Tests for authentication weaknesses:
- Brute force protection
- Weak password acceptance
- Session management
- Account lockout

### A08: Software/Data Integrity

Tests for integrity verification:
- Artifact signature verification
- SBOM integrity
- Attestation chain validation
- DSSE envelope validation

### A10: SSRF

Tests for server-side request forgery:
- Internal network access
- Cloud metadata endpoint blocking
- URL validation

## Writing Security Tests

### Base Class

All security tests should extend `SecurityTestBase`:

```csharp
using StellaOps.Security.Tests.Infrastructure;

[Trait("Category", "Security")]
[Trait("OWASP", "A01")]
public sealed class MySecurityTests : SecurityTestBase
{
    [Fact(DisplayName = "A01-XXX: Descriptive test name")]
    public void TestMethod()
    {
        // Arrange, Act, Assert
    }
}
```

### Naming Convention

- Test display names: `A{category}-{number}: {description}`
- Example: `A01-001: Admin endpoints should require authentication`

### Test Traits

Always include these traits:
- `Category = Security`
- `OWASP = A{category}`

## Security Test Guidelines

1. **Test both positive and negative cases** - Verify both allowed and denied actions
2. **Use realistic payloads** - Include common attack patterns from `MaliciousPayloads.cs`
3. **Don't rely on security by obscurity** - Assume attackers know the system
4. **Test boundaries** - Check edge cases and boundary conditions
5. **Document expected behavior** - Use descriptive test names and assertions

## Malicious Payloads

The `MaliciousPayloads.cs` file contains common attack patterns:

```csharp
public static class MaliciousPayloads
{
    public static readonly string[] SqlInjection = new[]
    {
        "' OR '1'='1",
        "1; DROP TABLE users--",
        "admin'--"
    };

    public static readonly string[] CommandInjection = new[]
    {
        "; rm -rf /",
        "| cat /etc/passwd",
        "$(whoami)"
    };

    public static readonly string[] PathTraversal = new[]
    {
        "../../../etc/passwd",
        "..\\..\\..\\windows\\system32\\config\\sam"
    };
}
```

## CI Integration

### Workflow Configuration

The security test job runs after build-test completes:

```yaml
security-testing:
  runs-on: ubuntu-22.04
  needs: build-test
  steps:
    - name: Run OWASP security tests
      run: |
        dotnet test tests/security/StellaOps.Security.Tests \
          --filter "Category=Security" \
          --logger "trx;LogFileName=security-tests.trx"
```

### Failure Handling

Security test failures:
- Block PR merge
- Generate detailed report
- Notify security team via webhook

## Reporting

Security test results are:
- Uploaded as CI artifacts
- Included in quality gate summary
- Tracked for trend analysis

## Related Documentation

- [OWASP Top 10](https://owasp.org/Top10/)
- [OWASP Testing Guide](https://owasp.org/www-project-web-security-testing-guide/)
- [Mutation Testing Guide](./mutation-testing-guide.md)
- [CI Quality Gates](./ci-quality-gates.md)