feat(security): add FIPS 140-3 compliance support

[bsbodden]

Summary

Add FIPS 140-3 compliance support so AMS can be deployed on FIPS-enabled hosts (e.g., RHEL 9 in FIPS mode) for federal government and regulated-industry deployments requiring FedRAMP compliance.

Problem: The existing bcrypt token hashing uses the Blowfish cipher, which is not a FIPS-approved algorithm. Redis connections lack explicit TLS configuration knobs needed for FIPS-compliant data-in-transit.

Solution: Make AMS "FIPS-capable" — when deployed on a FIPS-enabled host with the FIPS Docker image, all cryptographic operations use FIPS-approved algorithms via the host's validated OpenSSL module.

Changes

• Configurable token hashing (auth.py, config.py): New TOKEN_HASH_ALGORITHM setting supporting hmac-sha256 (default), pbkdf2-sha256, and bcrypt. Existing bcrypt hashes auto-detected and verified for backward compatibility via hash prefix detection (hmac$, pbkdf2$, $2b$).
• Redis TLS configuration (config.py, utils/redis.py): New settings for REDIS_SSL_CA_CERTS, REDIS_SSL_CERTFILE, REDIS_SSL_KEYFILE, REDIS_SSL_CERT_REQS, and REDIS_SSL_MIN_VERSION. TLS kwargs automatically applied when using rediss:// URLs or when CA certs are configured.
• FIPS diagnostics (fips.py, cli.py, healthcheck.py): New agent-memory fips-check CLI command and authenticated GET /v1/fips endpoint that report OpenSSL version, kernel FIPS mode, MD5 blocked status, configured token hash algorithm, Redis TLS status, and overall FIPS capability assessment.
• hashlib safety (utils/recency.py): Added usedforsecurity=False to SHA-256 calls used for deduplication (not security), preventing potential issues on strict FIPS OpenSSL configurations.
• FIPS Docker images (Dockerfile.fips): Multi-target Dockerfile with fips-ubi9 (Red Hat UBI 9) and fips-chainguard targets. Existing Dockerfile unchanged.
• cryptography bump (pyproject.toml): Minimum version raised to >=42.0.0 for proper OpenSSL 3.x FIPS provider support.

Crypto boundary coverage

Boundary	Algorithm	Status
Token hashing	HMAC-SHA256 / PBKDF2-SHA256	FIPS-approved
Memory dedup	SHA-256 (usedforsecurity=False)	FIPS-approved
JWT verification	RS256 via python-jose/cryptography	Already compliant
Random generation	secrets (OS CSPRNG)	Already compliant
Redis data-in-transit	TLS 1.2+ with configurable certs	Configurable

Backward compatibility

• Existing bcrypt token hashes continue to verify via automatic prefix detection
• Default algorithm changed to hmac-sha256 but bcrypt remains available
• No changes to existing Dockerfile or default non-FIPS deployment behavior
• All existing tests pass without modification

Test plan

• 24 new FIPS compliance tests (tests/test_fips_compliance.py)
• Updated token auth tests for new default hashing
• Full test suite: 727 passed, 0 failures
• Pre-commit (ruff, format, typos): all green
• Build Dockerfile.fips --target fips-ubi9 on FIPS-enabled host
• Verify GET /v1/fips endpoint returns correct diagnostics on FIPS host
• Verify agent-memory fips-check CLI output on FIPS host

---

Note

High Risk
Changes core token authentication hashing behavior (new default and new verification paths) and adds Redis TLS configuration, which can impact login validity and connectivity if misconfigured. Also introduces new FIPS diagnostic surfaces (CLI + authenticated API) that need to be reviewed for information exposure and operational expectations.

Overview
Adds a FIPS-capable deployment path by introducing Dockerfile.fips (UBI9 + Chainguard targets) and bumping cryptography to >=42.0.0 for OpenSSL 3.x/FIPS provider support.

Reworks token hashing to be configurable via settings.token_hash_algorithm with new FIPS-friendly schemes (hmac-sha256 default, pbkdf2-sha256, plus bcrypt), and updates verification to auto-detect hash formats by prefix for backward compatibility.

Adds Redis TLS knobs (redis_ssl_*) and applies them automatically in get_redis_conn() when using rediss:// or when CA certs are configured; also adds FIPS diagnostics via agent-memory fips-check and an authenticated GET /v1/fips endpoint, plus test coverage for hashing/TLS/diagnostics and usedforsecurity=False for SHA-256 used in non-security memory dedupe.

^{Written by Cursor Bugbot for commit 898fcc2. This will update automatically on new commits. Configure here.}

[github-actions]

FIPS compliance implementation looks solid overall with good test coverage and backward compatibility. A few security considerations identified below.

---

🤖 Automated review complete. Please react with 👍 or 👎 on the individual review comments to provide feedback on their usefulness.

[jit-ci]

🛡️ Jit Security Scan Results

✅ No security findings were detected in this PR

---

^{Security scan by Jit}

[cursor]

Cursor Bugbot has reviewed your changes and found 3 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

[Copilot]

Pull request overview

This PR adds FIPS 140-3 compliance support to the Agent Memory Server, enabling deployment in federal and regulated environments requiring FedRAMP compliance. The changes make the system "FIPS-capable" by switching from non-approved algorithms (bcrypt/Blowfish) to FIPS-approved alternatives (HMAC-SHA256, PBKDF2-SHA256) and adding configurable Redis TLS settings.

Changes:

• Introduces configurable token hashing with HMAC-SHA256 as the new default (replacing bcrypt), with backward compatibility for existing bcrypt hashes
• Adds Redis TLS configuration options (ca_certs, certfile, keyfile, cert_reqs, min_version)
• Provides FIPS diagnostics via new CLI command (fips-check) and authenticated API endpoint (GET /v1/fips)

Reviewed changes

Copilot reviewed 11 out of 12 changed files in this pull request and generated 20 comments.

Show a summary per file

File	Description
uv.lock	Updates cryptography minimum version to 42.0.0 for FIPS provider support
pyproject.toml	Updates cryptography minimum version to 42.0.0 for FIPS provider support
agent_memory_server/auth.py	Implements multi-algorithm token hashing with auto-detection; adds HMAC-SHA256 and PBKDF2-SHA256 support
agent_memory_server/config.py	Adds token hashing and Redis TLS configuration settings
agent_memory_server/utils/redis.py	Implements TLS kwargs builder for Redis connections based on URL scheme and settings
agent_memory_server/utils/recency.py	Adds usedforsecurity=False flag to SHA-256 calls used for deduplication
agent_memory_server/fips.py	New module providing FIPS compliance diagnostics (OpenSSL version, kernel FIPS mode, algorithm checks)
agent_memory_server/cli.py	Adds fips-check CLI command for runtime FIPS posture assessment
agent_memory_server/healthcheck.py	Adds authenticated /v1/fips endpoint for FIPS diagnostics
tests/test_fips_compliance.py	Comprehensive test suite covering token hashing algorithms, Redis TLS, and FIPS diagnostics
tests/test_token_auth.py	Updates tests for new default HMAC-SHA256 algorithm
Dockerfile.fips	New multi-target Dockerfile for FIPS-hardened images (UBI9 and Chainguard variants)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[tylerhutcherson]

Looks good in terms of providing Redis TLR and hashing algorithm updates. A few other questions/points:

@bsbodden We need documentation on connecting AMS to Redis w/ SSL enabled. This is something ideally we test before we hand over to customers too.

Do we need to maintain both Docker images?

[bsbodden]

Looks good in terms of providing Redis TLR and hashing algorithm updates. A few other questions/points:

1. We need documentation on connecting AMS to Redis w/ SSL enabled. ==> YES!
2. Do we need to maintain both Docker images? ==> The two recommended FIPS base images, yes. The non-compliant OSS one depends, but I think most user that do not care about FIPS would like to stay with a plain-vanilla Ubuntu image - so unfortunately, 3 docker images.

[github-actions]

This PR introduces FIPS 140-3 compliance support with configurable token hashing and Redis TLS configuration. I've identified a critical security issue with HMAC secret rotation that will invalidate all existing tokens, plus several other concerns around error handling and configuration validation.

---

🤖 Automated review complete. Please react with 👍 or 👎 on the individual review comments to provide feedback on their usefulness.

[github-actions]

Critical: HMAC secret rotation will invalidate all existing tokens

The HMAC-SHA256 implementation uses a single global token_hash_secret for both hashing and verification. If this secret is ever rotated (which is a security best practice), all existing HMAC-hashed tokens will immediately become invalid because verification uses the current secret.

Unlike PBKDF2 (which embeds the salt in the hash) or bcrypt (which is self-contained), HMAC requires the same secret key for verification. This creates an operational problem:

1. Tokens are stored in Redis with their hashes
2. If TOKEN_HASH_SECRET is rotated, verify_token_hash will fail for all existing HMAC tokens
3. Users will be locked out until tokens are regenerated

Suggested improvement:

Consider one of these approaches:

# Option 1: Support multiple secrets for gradual rotation
if token_hash.startswith("hmac$"):
    secrets_to_try = [
        settings.token_hash_secret,
        *settings.token_hash_secret_previous  # List of old secrets
    ]
    for secret in secrets_to_try:
        expected = "hmac$" + hmac.new(
            secret.encode("utf-8"),
            token.encode("utf-8"),
            hashlib.sha256
        ).hexdigest()
        if hmac.compare_digest(expected, token_hash):
            return True
    return False

# Option 2: Embed a key version in the hash format
# hmac$v1$<hash> where v1 maps to a specific secret
# This allows you to maintain multiple secrets indexed by version

This is a critical operational issue for production deployments where secret rotation is required for compliance.

[github-actions]

Missing error handling for invalid hex encoding

The int(iterations_str) and bytes.fromhex(salt_hex) calls can raise ValueError if the hash format is corrupted or maliciously crafted. While there's a catch-all exception handler at line 322, these specific parsing errors should be caught earlier to avoid logging warnings for expected validation failures.

Current code:

_, iterations_str, salt_hex, hash_hex = parts
iterations = int(iterations_str)  # Can raise ValueError
salt = bytes.fromhex(salt_hex)    # Can raise ValueError

Suggested improvement:

try:
    iterations = int(iterations_str)
    salt = bytes.fromhex(salt_hex)
    expected_hash = bytes.fromhex(hash_hex)  # Validate this too
except (ValueError, TypeError):
    return False

This prevents the catch-all exception handler from logging warnings for malformed input, which is expected during authentication attempts with invalid tokens.

[github-actions]

MD5 test may cause issues in strict FIPS mode

Testing MD5 availability by calling hashlib.md5(b"test") will raise a ValueError in strict FIPS mode, which is the intended behavior. However, this test doesn't distinguish between:

1. MD5 being blocked by FIPS (good)
2. MD5 being unavailable for other reasons (potentially bad)

Additionally, calling MD5 even for testing purposes may trigger security monitoring alerts in some environments.

Suggested improvement:

# Test if non-FIPS algorithms are blocked
try:
    # Use usedforsecurity=True to test if FIPS blocks it
    hashlib.md5(b"test", usedforsecurity=True)
    diagnostics["md5_blocked"] = False
except ValueError as e:
    # MD5 blocked - check if it's due to FIPS
    diagnostics["md5_blocked"] = "fips" in str(e).lower()
except Exception:
    # Other error - MD5 unavailable but not necessarily FIPS
    diagnostics["md5_blocked"] = None

This provides more nuanced diagnostics and explicitly uses usedforsecurity=True to make the intent clear.

[github-actions]

Case-sensitive string comparison may cause configuration errors

The cert_reqs_str.lower() call handles case-insensitivity, but if the user provides a value like "REQUIRED" in the environment variable and the code later compares it elsewhere without lowercasing, it could cause issues.

More importantly, there's no validation that redis_ssl_cert_reqs is one of the valid values. Invalid values silently fall back to ssl.CERT_REQUIRED, which could mask configuration errors.

Suggested improvement:

cert_reqs_str = settings.redis_ssl_cert_reqs.lower()
cert_reqs_map = {
    "required": ssl.CERT_REQUIRED,
    "optional": ssl.CERT_OPTIONAL,
    "none": ssl.CERT_NONE,
}
if cert_reqs_str not in cert_reqs_map:
    logger.warning(
        f"Invalid redis_ssl_cert_reqs value: {settings.redis_ssl_cert_reqs}. "
        f"Valid values are: required, optional, none. Defaulting to 'required'."
    )
cert_reqs = cert_reqs_map.get(cert_reqs_str, ssl.CERT_REQUIRED)

This provides explicit feedback when configuration is incorrect rather than silently using a default.

[github-actions]

Default secret is a security risk

While there's validation in verify_auth_config() that rejects the default secret when using HMAC-SHA256, the default value "change-me-in-production" is still problematic because:

1. It's visible in the codebase and could be used by attackers if validation is bypassed
2. It may be accidentally used in development and then promoted to production
3. The validation only runs when auth_mode == "token" or token_auth_enabled == True, but tokens could still be created via CLI even when auth is disabled

Suggested improvement:

token_hash_secret: str | None = None  # Force explicit configuration

# Then in verify_auth_config():
if settings.token_hash_algorithm == "hmac-sha256":
    if not settings.token_hash_secret:
        raise ValueError(
            "TOKEN_HASH_SECRET must be set when using hmac-sha256. "
            'Generate one with: python -c "import secrets; print(secrets.token_urlsafe(32))"'
        )

This forces explicit configuration and prevents accidental use of a weak default.

[github-actions]

Healthcheck may fail silently in restricted environments

The Chainguard healthcheck uses Python's urllib.request which may not handle connection errors gracefully in all environments. If the health check fails, the container will be marked unhealthy but the error won't be visible.

Current code:

CMD ["python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/v1/health')"]

Suggested improvement:

CMD ["python", "-c", "import sys, urllib.request; sys.exit(0 if urllib.request.urlopen('http://localhost:8000/v1/health').getcode() == 200 else 1)"]

This explicitly checks the status code and returns the appropriate exit code. Alternatively, consider installing curl in the Chainguard image for consistency with the UBI9 image, or use a simple Python script that provides better error handling.