Repository on GitHub, which provides public git repositories with URLs.

Repository on GitHub, which uses git. git can track the changes, who made them, and when they were made.

See CONTRIBUTION.md for PR strategy and how releases are made.

Repository on GitHub, which uses git. git is distributed.

https://github.com/dividor/evidencelab/releases

https://github.com/dividor/evidencelab/releases

Non-trivial release notes file in repository: https://github.com/dividor/evidencelab/blob/main/CHANGELOG.md.

https://github.com/dividor/evidencelab/releases

https://github.com/dividor/evidencelab/blob/main/CHANGELOG.md

Non-trivial SECURITY[.md] file found file in repository: https://github.com/dividor/evidencelab/blob/main/SECURITY.md. [osps_do_02_01]

GH Issues, templates etc in repo

On GitHub

https://github.com/dividor/evidencelab/issues?q=is%3Aissue%20state%3Aclosed

https://github.com/dividor/evidencelab/blob/main/SECURITY.md

https://github.com/dividor/evidencelab/blob/main/SECURITY.md

CONTRIBUTION.md provides instructions, plus online admin documentation, and GH actions CI.

Python packages managed with pip (requirements.txt), frontend built with npm/Create React App, containers built with Docker Compose. All are standard tools for this stack.

Extensive tests, documented in CONTRIBUTION.md

https://github.com/dividor/evidencelab/blob/main/.github/workflows/ci.yml

Combinations of e2e int tests and unit tests cover bulk of functionality

https://github.com/dividor/evidencelab/blob/main/.github/workflows/ci.yml

CLAUDE.md and CONTRIBUTION.md

The v1.2.0 release (the most recent major release) demonstrates consistent adherence to the test policy across all significant changes:

MCP server (PR #236) — shipped with 5 new test files: tests/unit/test_mcp_server.py (269 lines), tests/unit/test_mcp_auth.py (142 lines), tests/unit/test_mcp_audit.py (76 lines), tests/unit/test_mcp_config_descriptions.py (265 lines), and tests/integration/test_mcp_integration.py (194 lines).

A2A server (PR #240) — shipped with 3 new unit test files (test_a2a_agent_card.py, test_a2a_schemas.py, test_a2a_task_handler.py) and a new integration test suite (test_a2a_integration.py, 264 lines).

Security hardening (PR #241) — added tests/unit/test_encryption.py (128 lines) and tests/unit/test_mcp_ip_extraction.py (95 lines) covering the new encryption and IP-handling code.

Demo/CI mode (PR #242) — added tests/integration/demo_smoke_test.py (177 lines) as an end-to-end smoke test suite.

All PRs targeting the release branch ran the full CI test suite (pytest tests/unit/ and pytest tests/integration/) before merge.

CLAUDE.md and CONTRIBUTION.md

CONTRIBUTION.md, pre-commit hooks and CI

Warnings are enforced on every commit and in CI via pre-commit hooks and the code-quality CI job: flake8 (Python linting), mypy (Python type checking), bandit (Python security), and ESLint (TypeScript) all run automatically.

The small number of suppressions present are specific, justified false positives — not blanket silencing:

type: ignore[override] — mypy false positive on Starlette middleware dispatch() signatures where the base class type is intentionally looser

noqa: E402 — conditional/deferred imports in main.py that must appear after runtime configuration and cannot be moved to the top of the file

noqa: PLW0603 — module-level cache variables using global; a deliberate pattern for the API key cache

// @ts-ignore on import Plot from 'react-plotly.js' — the library ships no bundled TypeScript declarations
// eslint-disable react-hooks/exhaustive-deps — intentional omissions in useEffect dependency arrays where including the dep would cause infinite render loops
All other warnings raised by the toolchain are fixed in source rather than suppressed.

Python (backend + pipeline):

mypy runs on every commit via pre-commit, now without --no-strict-optional — full Optional/None checking enforced across all 44+ modules. Zero mypy errors in the codebase.
bandit runs at MEDIUM+HIGH severity (-ll) on every commit — upgraded from HIGH-only in v1.3.0. Four documented false-positive skips (B608, B104, B310, B113 in test/script code).
flake8 enforces PEP8 with 100-char line limit on every commit.
black + isort enforce formatting on every commit — zero style drift possible.
code-metrics pre-commit hook enforces cyclomatic complexity ≤20, cognitive complexity ≤20, and maintainability index ≥10 on every file.
Frontend (TypeScript/React):

ESLint runs in CI. (Note: if you didn't actually tighten ESLint settings as originally planned, don't claim it — check what's actually configured.)
"Where practical" carve-outs (be honest about these):

mypy does not run in full --strict mode (would require adding return types and typed arguments to all functions). The pragmatic limit is --no-strict-optional removed; full strict is future work.
Four bandit rules are skipped with documented justification in SECURITY.md.

Passwords are stored using Argon2id (primary) with bcrypt as a legacy fallback, via fastapi-users' PasswordHelper. Both algorithms are iterated hashes with per-user salts. Argon2id is OWASP's first recommendation for password storage and is resistant to GPU and side-channel attacks. The fallback to bcrypt is only used when verifying pre-existing bcrypt hashes during migration — new passwords are always hashed with Argon2id.

API keys use a different scheme by design: they are secrets.token_urlsafe(32) (256-bit random), stored as SHA-256 hashes. Key stretching is not required for high-entropy random tokens — it is only necessary for low-entropy user-chosen passwords. SHA-256 is appropriate here because brute-forcing a 256-bit random value is computationally infeasible regardless of hashing speed.

Yes. The project uses only publicly published, expert-reviewed cryptographic protocols: TLS 1.2/1.3 for transport, bcrypt for password hashing, SHA-256 for API key storage, HS256/RS256 for JWTs, and OAuth 2.0 for third-party authentication. No custom or proprietary cryptographic constructs are used anywhere in the codebase."

The project is an application whose primary purpose is document search and analysis, not cryptography. All cryptographic operations are delegated entirely to established libraries: bcrypt for passwords, python-jose for JWTs, Caddy/OpenSSL for TLS, httpx-oauth for OAuth 2.0, and Python's stdlib secrets/hashlib modules. No cryptographic algorithms are implemented in project code.

Transport security uses TLS 1.2/1.3 exclusively, explicitly configured in the Caddyfile (protocols tls1.2 tls1.3), disabling TLS 1.0/1.1 and all associated sub-2048-bit and weak cipher suites (RC4, 3DES). JWT uses HS256 with a minimum 256-bit secret key enforced at startup. Password hashing uses bcrypt. API keys are stored as SHA-256 hashes. All key lengths meet or exceed NIST SP 800-131A minimums through 2030. Weaker options are not configurable — TLS version and JWT algorithm are fixed, and the application fails to start if the JWT secret is below minimum length."

The software produced by this project uses no broken cryptographic algorithms (MD4, MD5, RC4, single DES, etc.) in any security mechanism. All security-relevant operations use SHA-256 or better, bcrypt, AES-GCM, HS256/HMAC-SHA256, and TLS 1.2/1.3 exclusively. MD5 appears in maintenance scripts solely as a non-cryptographic file-change detector, explicitly marked usedforsecurity=False in the Python stdlib call. Third-party dependencies (pypdf, websockets, requests) use MD5/SHA-1 only where required by interoperable protocols (PDF specification, RFC 6455 WebSocket handshake) — these are not configurable by this project.

The project's security mechanisms do not depend on cryptographic algorithms with known serious weaknesses. The one instance of CBC mode is in Python's Fernet library (used for API key encryption at rest), which mitigates all known CBC attacks via Encrypt-then-MAC (HMAC-SHA256 over the full ciphertext with a fresh random IV per message) — this is fundamentally different from the unauthenticated CBC that caused vulnerabilities in older SSH and TLS implementations. This is documented in SECURITY.md under 'Cryptographic Algorithms'. All other security mechanisms use AEAD constructions (AES-GCM, ChaCha20-Poly1305 for TLS), SHA-256, or bcrypt.

Yes. All HTTPS traffic is handled by Caddy, which provides perfect forward secrecy on all connections. TLS 1.3 (enabled by default) mandates ephemeral key exchange — PFS is guaranteed by the protocol. TLS 1.2 is restricted to ECDHE cipher suites only (Caddy's defaults exclude all RSA key exchange suites), so every TLS 1.2 session also uses ephemeral Diffie-Hellman. A compromise of the server's long-term TLS private key cannot be used to decrypt past recorded sessions. The protocols tls1.2 tls1.3 directive in the Caddyfile ensures no TLS version that lacks PFS can be negotiated."

Distribution channels use HTTPS exclusively. [osps_br_03_02]

Yes. Passwords are hashed using fastapi-users' PasswordHelper, which defaults to Argon2id (primary) with bcrypt as a legacy-hash fallback for verify_and_update. Argon2id is the OWASP Password Storage Cheat Sheet's top recommendation — it is memory-hard, uses a per-user random salt, and is iteratively stretched. No plaintext or reversibly-encrypted passwords are stored. The password history feature (ASVS V2.1.10) also stores only Argon2id hashes of previous passwords.

Dependabot it attentioned weekly

Gitleaks enabled on pre-commit and GH actions

Yes. Multiple static analysis tools run automatically on every proposed release via CI and pre-commit hooks, and the build fails if any of them report issues.

For Python, Bandit (SAST, security-focused, MEDIUM+HIGH severity) catches injection risks, hardcoded credentials, and unsafe API usage. mypy performs static type analysis with full Optional checking enforced. flake8 enforces style and detects common bugs. A custom complexity gate (scripts/quality/code_metrics.py) enforces cyclomatic complexity ≤20, cognitive complexity ≤20, and maintainability index ≥10 per file — the build fails if any function or file exceeds these thresholds.

For TypeScript/React, ESLint with eslint-plugin-security runs static analysis on every CI build.

For Dockerfiles, Hadolint runs static analysis on every commit.

All of these are FLOSS tools. They run on every commit via pre-commit hooks and again in CI on every pull request into rc/v* or main. No release can pass without all checks green.

Yes. Bandit is specifically designed to detect common security vulnerabilities in Python — it is not a general linter but a dedicated security SAST tool. It checks for OWASP Top 10 class issues including SQL injection, command injection, hardcoded credentials, use of unsafe functions (eval, exec, subprocess with shell=True), insecure deserialization, path traversal, weak cryptography, binding to all interfaces, and improper certificate validation. It runs at MEDIUM+HIGH severity on every commit and every CI build.

On the JavaScript/TypeScript side, eslint-plugin-security adds security-specific rules covering injection risks, unsafe regular expressions, non-literal require() calls, and object prototype pollution.

Both tools are purpose-built for vulnerability detection, not just style or correctness.

Bandit is configured to fail on MEDIUM and HIGH severity issues (-ll flag). It runs as a pre-commit hook — no code can be merged without passing it. CI additionally runs pre-commit --all-files on every PR, so the gate applies to the full codebase, not just changed files.

The remediation cycle is demonstrably short. In this release cycle (v1.3.0), two bandit findings were caught: B113 (missing request timeouts in compare_embeddings.py and dump_qdrant.py) — both fixed in the same PR before merge. The fix-before-merge workflow means vulnerabilities cannot land in a release branch without being resolved first.

The false positives that are suppressed (B310, B608, B104) are each documented in .pre-commit-config.yaml with an explanation of why they are not exploitable in context, so future reviewers can verify the judgment rather than just accepting a blind skip.

SECURITY.md documents the process under "Tools Reference" and the PR security checklist explicitly requires bandit to pass before submission. The practical policy is: bandit finding at MEDIUM+ = commit blocked = must fix before the branch can be merged. There is no override path — --no-verify is prohibited by CLAUDE.md

Every commit.

Trivy scans all production container images before release, catching CVEs in OS packages and runtime dependencies that static analysis cannot see. Integration tests additionally exercise the running application against live services (real Postgres, Qdrant, FastAPI). Both run in CI as release gates.