# CodeQL Local Validation Tool

This directory contains development and validation tools for the SousChef project.

Companion docs:

- [LOCAL_CODEQL_GUIDE.md](LOCAL_CODEQL_GUIDE.md) — full guide to running CodeQL locally
- [CODEQL_QUICK_REFERENCE.md](CODEQL_QUICK_REFERENCE.md) — quick reference card

## check_codeql_suppressions.py

A local validation tool that verifies CodeQL path-injection security suppressions are in place before pushing code to GitHub.

### What It Does

CodeQL is GitHub's code analysis tool that detects potential security vulnerabilities, including "path-injection" attacks where user input could be used unsafely in file path operations.

This tool validates that:

- All path operations that could be flagged by CodeQL have proper inline suppressions
- The suppression format is correct: `# codeql [py/path-injection]` (with space)
- All files with path operations are checked

### Running the Tool

```bash
python3 tools/check_codeql_suppressions.py
```

### Output Examples

**Success (all suppressions in place):**

```text
======================================================================
LOCAL CODEQL SUPPRESSION VALIDATION
======================================================================

Checking souschef/assessment.py:
  [OK] 49/23 suppressions found (PERFECT)
...
[OK] ALL SUPPRESSIONS IN PLACE!
[OK] Ready to push to GitHub
```

**Failure (missing suppressions):**

```text
Checking souschef/assessment.py:
  [FAIL] 22/30 suppressions found (MISSING 8)
...
FILES WITH MISSING SUPPRESSIONS:
  souschef/assessment.py: Missing 8 suppressions
```

### Why This Matters

CodeQL runs on every push to GitHub and will block PRs if security warnings are not properly addressed. This tool lets you catch and fix issues **locally before pushing**, saving time and preventing CI failures.

### Understanding CodeQL Suppressions

CodeQL suppressions must:

1. Use the exact format: `# codeql [py/path-injection]` (note the space between "codeql" and "[")
2. Be on the **same line** as the path operation that triggered the warning
3. Only suppress issues that are actually safe (e.g., paths normalized via `_normalize_path()` or `_safe_join()`)

**Example:**

```python
# Safe: cookbook_path is normalized by caller via _normalize_path()
recipe_path = cookbook_path / "recipes" / recipe_name  # codeql [py/path-injection]
```

### Files Checked

- `souschef/assessment.py` - Cookbook assessment logic with path operations
- `souschef/server.py` - MCP server with databag and environment file operations
- `souschef/ui/pages/cookbook_analysis.py` - Streamlit UI with archive extraction
- `souschef/core/path_utils.py` - Path validation utilities
- `souschef/ui/app.py` - Main Streamlit application

### Integration with Development Workflow

Before committing path operation changes:

```bash
# 1. Make your changes
# 2. Run local validation
python3 tools/check_codeql_suppressions.py

# 3. If successful, commit and push
git commit -m "feat: add path operation"
git push origin main

# 4. Monitor GitHub Actions for CodeQL results
```

### Common Issues

**Issue:** "Missing suppressions" reported
**Solution:** Check that the suppression comment is on the exact line with the path operation, not on a separate comment line.

**Issue:** CodeQL still complains on GitHub
**Solution:** Ensure the suppression format is exactly `# codeql [py/path-injection]` with the space. Also verify the path operation is actually safe (normalized before use).

### Troubleshooting

To see which files have suppressions:

```bash
grep -r "codeql \[py/path-injection\]" souschef/
```

To count total suppressions:

```bash
grep -r "codeql \[py/path-injection\]" souschef/ | wc -l
```

To check a specific file:

```bash
grep "codeql \[py/path-injection\]" souschef/assessment.py | wc -l
```

### For More Information

- [CodeQL Documentation](https://codeql.github.com/)
- [SousChef Security Guidelines](../SECURITY.md)
- [SousChef Architecture](../docs/ARCHITECTURE.md)
