Skip to content

rapor3.md

Latest commit

 

History

History
275 lines (196 loc) · 8.18 KB

rapor3.md

File metadata and controls

275 lines (196 loc) · 8.18 KB
Raw

Provider Security Hardening Report

1. Summary of changes

This task hardened the provider layer in three areas:

Provider sandboxing

  • added explicit provider trust levels
  • added provider readiness states
  • added request context minimization and prompt sanitization
  • added structured provider response validation
  • added trust-aware suppression of executable command suggestions
  • preserved the normal plan -> risk review -> approval path for all provider output

Credential validation

  • added provider configuration validation before provider use
  • added endpoint URL validation
  • added missing / placeholder credential detection
  • added clearer failure classification for configuration, authentication, network, model, and response failures
  • surfaced readiness, trust, and validation state through provider status and health output

Secret-at-rest protection

  • added env-var-first secret resolution
  • added optional keyring-backed secret resolution
  • added plaintext secret storage detection for config storage
  • added redaction for provider-related errors and audit/session logging payloads
  • documented that .env is convenience-oriented and not secure secret storage

2. Architecture changes

Main files changed:

  • src/komu_cli/models/providers.py
  • src/komu_cli/models/config.py
  • src/komu_cli/providers/base.py
  • src/komu_cli/providers/http_client.py
  • src/komu_cli/providers/adapters/ollama.py
  • src/komu_cli/providers/adapters/openai_compatible.py
  • src/komu_cli/providers/adapters/openai.py
  • src/komu_cli/providers/adapters/claude.py
  • src/komu_cli/providers/adapters/gemini.py
  • src/komu_cli/services/provider_service.py
  • src/komu_cli/services/provider_security_service.py
  • src/komu_cli/services/config_service.py
  • src/komu_cli/logging/audit.py
  • src/komu_cli/security/redaction.py
  • src/komu_cli/security/secrets.py

New abstractions introduced:

  • provider trust model
  • provider readiness model
  • provider validation result / issue models
  • provider security service for request/response hardening
  • secret resolution abstraction with optional keyring support
  • shared redaction helpers

Integration direction:

  • adapters now validate config and expose trust/readiness state
  • provider service now sanitizes requests and validates responses
  • config service now reports plaintext secret-storage risks
  • logging now redacts payloads before writing audit/session records
  • CLI provider views now expose trust, readiness, and validation information

3. Sandboxing model

Provider trust levels

The provider layer now uses:

  • trusted
  • restricted
  • untrusted

Default posture:

  • official hosted providers are generally trusted
  • local/self-hosted providers such as Ollama default to restricted
  • remote custom OpenAI-compatible endpoints default to untrusted

Context minimization strategy

Provider requests now go through a sanitization pass:

  • secret-like prompt fragments are redacted
  • sensitive context keys are removed
  • context size is bounded
  • context value length is bounded
  • safety notes are attached to the provider request

This prevents accidental leakage of raw secrets, full config state, or unrelated heavy context by default.

Provider output validation strategy

Provider responses are now validated before the rest of the system uses them:

  • provider key must match the adapter
  • summary must be non-empty
  • plan steps must be present and bounded
  • warning count is bounded
  • command suggestion count is bounded
  • command stages are restricted to known values
  • invalid or malformed command suggestions are rejected

No-bypass enforcement summary

Provider output still cannot bypass:

  • plan construction
  • plan review
  • risk classification
  • approval requirements
  • execution visibility

Additional enforcement:

  • untrusted providers have executable command suggestions suppressed by default
  • restricted providers can lose executable suggestions for sensitive tasks

4. Credential validation changes

Validation now covers:

  • missing API key detection
  • placeholder API key detection
  • missing model detection
  • placeholder model detection
  • missing endpoint detection
  • invalid endpoint URL detection
  • optional secret backend availability warnings

Readiness now distinguishes:

  • ready
  • restricted
  • needs-configuration
  • unavailable

Failure classes now distinguish:

  • configuration
  • authentication
  • network
  • model
  • response

Where this is surfaced:

  • komu providers list
  • komu providers current
  • komu providers health
  • komu providers check <provider>
  • komu config show

5. Secret handling changes

Env var preference

Secrets are now resolved in this order:

  1. direct environment variable
  2. optional keyring backend when enabled
  3. missing if neither path resolves a value

Plaintext secret warnings

KOMU now scans stored config payloads for secret-like keys such as:

  • api_key
  • token
  • secret
  • password
  • credential

If plaintext secret-like fields are found in config storage, KOMU reports that as a warning.

Keyring support

Optional support was added through a lightweight abstraction:

  • enable with KOMU_SECRET_BACKEND=keyring
  • service name defaults to komu-cli
  • can be changed with KOMU_KEYRING_SERVICE

This support is optional and does not require a hard dependency in the base package.

Redaction behavior

Redaction now applies to:

  • provider-related error paths
  • HTTP error text returned by provider transport
  • audit log payloads
  • session log payloads
  • prompt/context sanitization before provider invocation

6. Testing summary

New or expanded tests:

  • tests/test_provider_security_service.py

    • request context minimization
    • prompt redaction
    • trust-aware command suppression
    • malformed provider output rejection

  • tests/test_provider_adapters.py

    • missing credential validation
    • invalid endpoint validation
    • placeholder secret rejection
    • remote custom endpoint trust posture
    • failure-kind classification on health errors

  • tests/test_provider_service.py

    • sanitized provider request flow
    • untrusted provider downgrade behavior
    • malformed provider response fallback behavior

  • tests/test_planning_service_provider_security.py

    • provider-generated commands still flow through risk and approval review

  • tests/test_secret_handling.py

    • secret redaction
    • env-var-first secret resolution
    • keyring backend warning path

  • tests/test_config_service.py

    • plaintext secret storage warning detection

Validation run after implementation:

  • python -m unittest discover -s tests -p "test_*.py" passed with 57 tests
  • python -m compileall src passed

What remains untested:

  • real live provider integrations against public remote APIs
  • real live keyring backend behavior on each OS
  • every possible custom OpenAI-compatible endpoint variant

7. Compatibility / limitations

Important tradeoffs made to preserve stability:

  • provider sandboxing is policy-aware application-layer hardening, not OS container isolation
  • keyring support is optional and intentionally lightweight
  • remote custom endpoints are treated conservatively by default rather than optimistically
  • provider trust does not replace the plan/risk/approval model; it narrows provider influence

Deferred or partial areas:

  • no full OS-specific secret manager integration matrix yet
  • no multi-tenant secret policy model yet
  • no dynamic benchmark-based provider trust scoring
  • no cryptographic storage of secrets in KOMU-managed files

8. Recommended next steps

Immediate next hardening tasks:

  • add live integration validation against at least one real hosted provider and one real local provider
  • add more explicit CLI messaging for configuration vs trust vs reachability failures
  • expand secret redaction tests around audit/session history reads
  • add provider trust state to explanation/history views where useful

If KOMU moves toward broader public use next:

  • add deeper keyring/backend guidance per operating system
  • add stricter provider policy packs for enterprise or regulated environments
  • add export-safe audit/report generation with stronger redaction guarantees
  • add a richer operator-facing security status view that summarizes provider trust, readiness, and secret-storage risks in one place