/.github/SECURITY_ALERTS.md

# Security Alert Assessment

This document explains the security scanning alerts that have been assessed
and determined to be false positives or intentionally suppressed.

## DS162092 - Hardcoded URLs

**Status:** Excluded in DevSkim workflow via `exclude-rules`

### Explanation

This rule is excluded because this research tool legitimately integrates with
external APIs. All hardcoded URLs are intentional service endpoints:

- **ArXiv** - Academic paper repository (`https://arxiv.org/`)
- **PubMed** - Medical literature database
- **Semantic Scholar** - AI-powered research tool
- **OpenAlex** - Open catalog of scholarly works
- **Archive.org** - Wayback Machine integration

### Why Exclusion Is Safe

1. **Legitimate API endpoints** - URLs are for real research services
2. **SSRF protection** - Production code uses
   `src/local_deep_research/security/ssrf_validator.py` to block dangerous URLs
3. **No user-controlled URLs** - All URLs are hardcoded service endpoints
4. **Test coverage** - URL handling is tested in `tests/fuzz/test_security_fuzzing.py`

---

## DS137138 - Hardcoded Credentials

**Status:** Excluded via workflow configuration (no action needed)

### Explanation

All ~100+ hardcoded credential alerts are in the `tests/` directory and are
intentional mock data for testing.

### Why They Are Safe

1. **All instances are test fixtures** - Named clearly as mock data:
   - `api_key="test_key"`
   - `password="testpass"`
   - `sample_data_with_secrets()`

2. **DevSkim already excludes tests** - The `.github/workflows/devskim.yml`
   configuration includes:
   ```yaml
   ignore-globs: 'examples/**,tests/**'
   ```

3. **Never real credentials** - All test values are obviously fake

4. **Gitleaks handles real secrets** - The `.github/workflows/gitleaks.yml`
   workflow scans for actual leaked credentials

### Example Test Fixtures

- `tests/fixtures/mock_credentials.py`
- `tests/unit/auth/test_login.py`
- `tests/integration/api/test_authentication.py`

---

## DS172411 - JavaScript DOM (innerHTML)

**Status:** Addressed with XSS protection infrastructure

### Explanation

The codebase has comprehensive XSS protection infrastructure in
`src/local_deep_research/web/static/js/security/xss-protection.js`:

| Protection Function | Purpose |
|---------------------|---------|
| `escapeHtml()` | HTML entity escaping for text content |
| `sanitizeHtml()` | DOMPurify-based HTML sanitization |
| `safeSetInnerHTML()` | Safe innerHTML wrapper |
| `sanitizeUserInput()` | User input validation and sanitization |

### Current Status

| Category | Count | Status |
|----------|-------|--------|
| Using `escapeHtml()` | ~35 | Safe |
| Using `textContent` | ~20 | Safe |
| Static HTML only | ~15 | Safe |
| Using `sanitizeHtml()` | ~5 | Safe |

All innerHTML usages have been reviewed and appropriate sanitization applied.

---

## DS176209 - Suspicious Comments

**Status:** Excluded in DevSkim workflow via `exclude-rules`

### Explanation

DevSkim flags comments containing words like `TODO`, `FIXME`, `HACK`, `BUG`,
`XXX` as "suspicious". These are **standard development annotations** used
to track technical debt and future work.

### Why Exclusion Is Safe

1. **Not a security rule** - This is a code quality check, not security
2. **Standard practice** - TODO/FIXME comments are used in every codebase
3. **No runtime impact** - Comments have no effect on application behavior
4. **IDE support** - Development tools already track these annotations

---

## DS126858 - Weak/Broken Hash Algorithm

**Status:** Excluded in DevSkim workflow via `exclude-rules`

### Explanation

DevSkim flags any literal occurrence of `sha1` as a "weak/broken hash
algorithm". In this codebase the only matches are:

1. **SLSA provenance JSON keys** in `.github/workflows/prerelease-docker.yml` —
   the `"sha1"` key inside `digest` objects is part of the
   [SLSA in-toto provenance schema](https://slsa.dev/spec/v0.2/provenance) and
   identifies the algorithm Git itself uses for commit hashes. We are not
   choosing SHA-1 as a cryptographic primitive — Git's commit identifier
   format is fixed.

2. **SQLCipher KDF/HMAC algorithm enums** in
   `src/local_deep_research/settings/env_definitions/db_config.py`
   (`PBKDF2_HMAC_SHA1`, `HMAC_SHA1`). These exist for backwards-compatibility
   with existing user databases; the default is SHA-512. Each occurrence
   carries an inline `# DevSkim: ignore DS126858` annotation with rationale.

### Why Exclusion Is Safe

1. **Not a cryptographic choice** - The `sha1` strings in SLSA provenance are
   *protocol-mandated key names*, not crypto operations we control.
2. **Git's commit hashing is SHA-1 by design** - The Linux kernel and every
   git-backed project produces SHA-1 commit IDs; SLSA records them honestly.
3. **Real SHA-1 misuse would be reviewed** - The SQLCipher backwards-compat
   uses are documented and reviewed; new uses of SHA-1 as a cryptographic
   primitive would be caught in code review and by CodeQL.
4. **No password/signature SHA-1 in this codebase** - Authentication uses
   `secrets`/Argon2-class KDFs and SQLCipher's SHA-512 default.

---

## Container Image CVEs

**Status:** Documented, awaiting upstream fixes

### No Fix Available

The following CVEs are in the Debian base image packages with no upstream
fixes currently available:

| CVE | Package | Severity | Notes |
|-----|---------|----------|-------|
| CVE-2025-14104 | util-linux | Medium | No fix version |
| CVE-2022-0563 | util-linux | Low | Debian won't fix |
| CVE-2025-6141 | Various | Low | No fix version |

These are monitored and will be addressed when fixes become available.

---

## DevSkim Rule Exclusions Summary

The following rules are excluded in `.github/workflows/devskim.yml`:

| Rule | Name | Reason |
|------|------|--------|
| DS162092 | Hardcoded URL | Legitimate API endpoints for research services |
| DS176209 | Suspicious Comment | Standard TODO/FIXME annotations |
| DS137138 | Hardcoded Credentials | All matches are test fixtures (mock data) |
| DS148264 | Use cryptographic random | All `random` usages are non-security (ML shuffle, jitter) |
| DS172411 | setTimeout code injection | All setTimeout calls pass function refs, never strings |
| DS126858 | Weak/Broken Hash Algorithm | SLSA-schema-required `sha1` JSON key + SQLCipher backwards-compat enums |

### Review Cadence

These exclusions should be reviewed **quarterly** to ensure:
- No new security-relevant URLs are being masked
- Exclusions remain appropriate as the codebase evolves
- New DevSkim rules are evaluated for applicability

**Last reviewed:** May 2026

---

## GitHub Security Tab Dismissals

Some security alerts can only be dismissed, or are very difficult to
suppress, outside the
[GitHub Security tab](https://docs.github.com/en/code-security/dependabot/dependabot-alerts/viewing-and-updating-dependabot-alerts).
This is a
[GitHub platform limitation](https://github.com/orgs/community/discussions/163277) —
Dependabot alerts, code scanning alerts, and secret scanning alerts are
managed primarily through the repository UI rather than via configuration
files or inline annotations.

Dismissals made through the Security tab include a reason (e.g.,
"tolerable in this context", "no bandwidth to fix", "false positive") and
an optional comment, but these are only visible to users with repository
write access. GitHub provides no export or in-repo tracking mechanism, so
unlike the other suppressions documented in this file, these dismissals
cannot be tracked in version-controlled files.

---

## References

- [DevSkim Configuration](workflows/devskim.yml)
- [Gitleaks Configuration](workflows/gitleaks.yml)
- [XSS Protection Module](../src/local_deep_research/web/static/js/security/xss-protection.js)
- [SSRF Validator](../src/local_deep_research/security/ssrf_validator.py)