# CI Pipeline - Complete Security Suite

**Enhanced CI/CD pipeline with comprehensive security scanning layers.**

---

## 🎯 What Changed

### ❌ Removed
- **`ansible/` directory** - Moved to infrastructure repository (where it belongs)
- **`ANSIBLE_INTEGRATION.md`** - Redundant with handoff docs

### ✅ Kept (Reference Documentation)
- **`ANSIBLE_HANDOFF.md`** - Integration guide for your Ansible team
- **`ANSIBLE_TECHNICAL_REFERENCE.md`** - Exact commands, paths, procedures
- **`CUSTOMIZATION_CHECKLIST.md`** - Configuration reference
- **`MOVE_ANSIBLE_TO_SEPARATE_REPO.md`** - Migration guide

### 🚀 Enhanced
- **`.github/workflows/ci.yml`** - Added 5 new security scanning jobs

---

## 🔐 Security Layers

### 1. Secret Scanning (Gitleaks)
**Tool:** [Gitleaks](https://github.com/gitleaks/gitleaks)  
**Purpose:** Detect exposed secrets in code and git history

**Scans for:**
- API keys
- Passwords
- Tokens
- Private keys
- Database credentials

**Features:**
- Scans entire git history (`fetch-depth: 0`)
- Redacted output (doesn't expose secrets in logs)
- Continues on error (won't block CI)

```yaml
container: zricethezav/gitleaks:latest
command: gitleaks detect --source . --no-banner --redact --exit-code 0
```

---

### 2. Security Scan (Safety + Bandit)
**Tools:** [Safety](https://pyup.io/safety/) + [Bandit](https://bandit.readthedocs.io/)

#### Safety - Dependency Vulnerabilities
**Purpose:** Check Python dependencies against CVE database

**Scans for:**
- Known vulnerabilities in packages
- Outdated packages with security issues
- CVE references

```bash
pip install safety
safety check --json
```

#### Bandit - Static Security Analysis
**Purpose:** Find common security issues in Python code

**Scans for:**
- SQL injection vulnerabilities
- Hardcoded passwords
- Use of `eval()`, `exec()`
- Insecure temp file usage
- Weak cryptography

```bash
pip install bandit
bandit -r src/ -f screen
```

---

### 3. Dependency Scan (Trivy)
**Tool:** [Trivy](https://github.com/aquasecurity/trivy)  
**Purpose:** Comprehensive vulnerability scanner

**Scans:**
- Python packages (from `pyproject.toml`)
- System libraries
- OS packages
- CVE database

```yaml
container: aquasec/trivy:latest
command: trivy fs --scanners vuln --exit-code 0 .
```

---

### 4. SAST Scan (Semgrep)
**Tool:** [Semgrep](https://semgrep.dev/)  
**Purpose:** Static Application Security Testing

**Scans for:**
- Security anti-patterns
- Code quality issues
- Language-specific vulnerabilities
- OWASP Top 10 issues

**Features:**
- Language-aware (understands Python syntax)
- Pattern-based matching
- Auto-config uses community rules

```bash
pip install semgrep
semgrep --config=auto --error
```

---

### 5. Container Scan (Trivy)
**Tool:** Trivy (filesystem mode)  
**Purpose:** Scan Docker configurations and filesystem

**Scans:**
- `Dockerfile` misconfigurations
- Filesystem vulnerabilities
- HIGH/CRITICAL severity issues

**Features:**
- Config scanning (Dockerfile best practices)
- Filesystem scanning (all files)
- Severity filtering

```bash
trivy config Dockerfile
trivy fs --scanners vuln --severity HIGH,CRITICAL --format table .
```

---

## 📊 CI Pipeline Jobs

### Complete Job List

| Job | Purpose | Tool(s) | Blocking? |
|-----|---------|---------|-----------|
| **lint-and-test** | Code quality & tests | ruff, black, mypy, pytest | ✅ Yes |
| **secret-scanning** | Exposed secrets | Gitleaks | ⚠️ No |
| **security-scan** | Python security | Safety, Bandit | ⚠️ No |
| **dependency-scan** | Dependency vulns | Trivy | ⚠️ No |
| **sast-scan** | Static analysis | Semgrep | ⚠️ No |
| **container-scan** | Container security | Trivy | ⚠️ No |
| **docker-build-test** | Docker build | Docker | ✅ Yes |
| **workflow-summary** | Status report | Native | ℹ️ Info |

### Blocking vs Non-Blocking

**Blocking (will fail CI):**
- `lint-and-test` - Code must pass tests
- `docker-build-test` - Docker image must build

**Non-Blocking (informational):**
- All security scans use `continue-on-error: true`
- Provides visibility without blocking development
- Can be made blocking by removing `continue-on-error`

---

## 🎨 Workflow Summary

After all jobs complete, a summary is generated:

```
## 🔍 CI Workflow Summary

### Job Results

| Job | Status |
|-----|--------|
| 🧪 Lint & Test | success |
| 🔐 Secret Scanning | success |
| 🔒 Security Scan | success |
| 📦 Dependency Scan | success |
| 🔍 SAST Scan | success |
| 🐳 Container Scan | success |
| 🐋 Docker Build | success |

### 📊 Summary

All security and validation checks have completed.

**Security Layers:**
- ✅ Secret scanning (Gitleaks)
- ✅ Dependency vulnerabilities (Safety + Trivy)
- ✅ Static security analysis (Bandit)
- ✅ SAST scanning (Semgrep)
- ✅ Container scanning (Trivy)
```

---

## 🔧 Configuration

### Gitea Secrets (Optional)

None of the security scans require secrets, but you can configure:

```bash
# Optional: For SonarQube integration (if you add it later)
SONAR_HOST_URL=https://sonar.example.com
SONAR_TOKEN=your_token_here
```

### Making Scans Blocking

To make security scans fail the build, remove `continue-on-error: true`:

```yaml
# Before (non-blocking):
- name: Scan for secrets
  run: gitleaks detect --source . --no-banner --redact --exit-code 0
  continue-on-error: true

# After (blocking):
- name: Scan for secrets
  run: gitleaks detect --source . --no-banner --redact --exit-code 1
  # Removed continue-on-error
```

---

## 📈 Comparison with Your Ansible Pipeline

### Features from Your Pipeline

| Feature | Your Ansible Pipeline | POTE Pipeline | Status |
|---------|----------------------|---------------|--------|
| Markdown linting | ✅ npm run test:markdown | ❌ N/A | Not needed (Python project) |
| Ansible validation | ✅ ansible-lint | ❌ Removed | Moved to infrastructure repo |
| Secret scanning | ✅ Gitleaks | ✅ Gitleaks | ✅ Implemented |
| Dependency scan | ✅ Trivy | ✅ Trivy | ✅ Implemented |
| SAST scan | ✅ Semgrep | ✅ Semgrep | ✅ Implemented |
| License check | ✅ license-checker (npm) | ❌ N/A | Not needed (MIT license) |
| Vault check | ✅ Ansible vault | ❌ Removed | No vault files in app repo |
| Playbook test | ✅ ansible-playbook | ❌ Removed | No playbooks in app repo |
| Container scan | ✅ Trivy | ✅ Trivy | ✅ Implemented |
| SonarQube | ✅ sonar-scanner | ❌ Not added | Can add if needed |

### What's Different

**Removed (Ansible-specific):**
- Ansible linting
- Vault validation
- Playbook syntax checks
- Markdown linting (not applicable)

**Added (Python-specific):**
- Python linting (ruff, black, mypy)
- pytest with coverage
- Safety (Python dependency CVE check)
- Bandit (Python security linter)

**Kept (Universal):**
- Secret scanning (Gitleaks)
- Dependency scanning (Trivy)
- SAST scanning (Semgrep)
- Container scanning (Trivy)

---

## 🚀 Usage

### Triggers

The pipeline runs on:
```yaml
on:
  push:
    branches: [main, qa, dev]
  pull_request:
    branches: [main, qa, dev]
```

### Manual Trigger

To trigger manually (if you add `workflow_dispatch`):
```yaml
on:
  workflow_dispatch:  # Add this
  push:
    branches: [main, qa, dev]
  pull_request:
    branches: [main, qa, dev]
```

Then trigger via Gitea UI: Actions → CI → Run workflow

---

## 📊 Viewing Results

### In Gitea

1. **Navigate to:** Repository → Actions → CI workflow
2. **Click on:** Latest run
3. **View:** Individual job logs
4. **Summary:** Scroll to bottom for workflow summary

### Locally

Run the same checks locally before pushing:

```bash
# Linting
ruff check src/ tests/
black --check src/ tests/
mypy src/

# Tests
pytest tests/ -v --cov=src/pote

# Security scans (if tools installed)
gitleaks detect --source . --no-banner
safety check
bandit -r src/
semgrep --config=auto src/
trivy fs .
```

---

## 🔄 Future Enhancements

### Optional Additions

1. **SonarQube Integration**
   - Code quality metrics
   - Technical debt tracking
   - Requires SonarQube server

2. **License Checking**
   - Scan Python dependencies for licenses
   - Tool: `pip-licenses`

3. **Performance Testing**
   - Benchmark critical functions
   - Tool: `pytest-benchmark`

4. **Code Coverage Gates**
   - Fail if coverage drops below threshold
   - Already have coverage reporting

5. **Dependency Updates**
   - Auto-create PRs for dependency updates
   - Tool: Dependabot or Renovate

---

## 🆘 Troubleshooting

### Job Failing: secret-scanning

**Issue:** Gitleaks found exposed secrets

**Solution:**
1. Review the scan output (redacted)
2. Remove secrets from code
3. Use `.env` files (already in `.gitignore`)
4. Rotate exposed credentials

### Job Failing: security-scan

**Issue:** Safety found vulnerable dependencies

**Solution:**
1. Review `safety check` output
2. Update vulnerable packages: `pip install --upgrade <package>`
3. Update `pyproject.toml` with new versions

### Job Failing: sast-scan

**Issue:** Semgrep found security issues

**Solution:**
1. Review Semgrep output
2. Fix identified issues
3. Add `# nosemgrep` comment if false positive

### Job Failing: container-scan

**Issue:** Trivy found HIGH/CRITICAL vulnerabilities

**Solution:**
1. Review Trivy output
2. Update base image in `Dockerfile`
3. Update system packages

---

## 📝 Best Practices

### 1. Review Security Scan Results
- Don't ignore security warnings
- Investigate all HIGH/CRITICAL findings
- Keep dependencies up to date

### 2. Use Secrets Management
- Never commit secrets
- Use Gitea secrets for CI/CD
- Use `.env` files locally (in `.gitignore`)

### 3. Keep Tools Updated
- Security tools are frequently updated
- Pin versions for stability
- Update quarterly

### 4. Make Critical Scans Blocking
- Consider making secret scanning blocking
- Consider making HIGH/CRITICAL vulnerability scans blocking

---

## 📞 Support

- **CI Pipeline Issues:** Check `.github/workflows/ci.yml`
- **Security Tool Docs:**
  - [Gitleaks](https://github.com/gitleaks/gitleaks)
  - [Safety](https://pyup.io/safety/)
  - [Bandit](https://bandit.readthedocs.io/)
  - [Trivy](https://github.com/aquasecurity/trivy)
  - [Semgrep](https://semgrep.dev/)

---

**Last Updated:** December 2025  
**Pipeline Version:** 2.0 (Enhanced Security Suite)  
**Total Security Layers:** 5