Channel and gateway examples must not persist raw secrets

Aperta
#5,783 1 commento 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

  • #5787 di @praisonai-triage-agent — chiusa senza merge

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
35/100
Tipo di issue
Refactoring
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
docker-compose, kubernetes, python
Ambito
devops, security

Direzione di ricerca

Start with examples/gateway/demo.yaml, which the issue shows holding a literal bot_token, and run rg "xoxb-|sk-[A-Za-z0-9]{20}" examples/ to find every other hit. The env:VAR resolution idea is sketched in resolve_config_value, but the channel service handler and the GET /api/channels path are not shown in the payload, so locate them first. Done means the scan returns no matches and secret fields are not echoed on GET. The linked PR #5787 was closed unmerged, so check why before starting.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

bug claude documentation security

Channel and gateway examples must not persist raw secrets

Type

Security

Labels

security · gateway · examples


Summary

Dimension Detail
Risk Example scripts teach operators to persist plaintext credentials
Impact Backups, logs, and config exports leak live secrets
Fix theme Runtime resolution from environment or secret manager references
Verification Repo scan + secure reference examples per channel type

Problem

Gateway channel registration accepts JSON configuration. When examples POST bodies containing raw tokens, operators copy the pattern into durable stores (config.yaml, channel database rows). Settings and secrets collapse into one bucket — any config read becomes a secret leak.


Trust boundary diagram

┌────────────────┐  POST /api/channels   ┌─────────────────┐
│ Example script │ ─────────────────────►│ Channel service │
└────────────────┘  {token: "..."}       └────────┬────────┘
                                                    │ persist
                                                    ▼
                                         ┌─────────────────────┐
                                         │ Durable config store │
                                         └────────┬────────────┘
                                                    │
                    ┌───────────────────────────────┼───────────────────────────────┐
                    ▼                               ▼                               ▼
              Admin GET                        Backup S3                      Support export
              (leaks secret)                   (leaks secret)                 (leaks secret)

Target state:

Example → config uses env:VAR references → gateway resolves at runtime → store holds reference only

Expected vs actual

Pattern Expected Anti-pattern
Bot token registration Value from environment at process start Literal string in committed YAML
Gateway admin auth Token via env on deploy Token in Helm values committed to git
Email/IMAP Secret manager or env Password field in tutorial JSON
Sample compose files .example suffix Working file with real creds
Docs screenshot Redacted placeholders Visible token substring

Secret vs setting classification

Field Class Persistence rule Failure mode
config.api_key Secret Reject persist or store ref token Plain string accepted
config.bot_token Secret env: prefix only in samples xoxb- pattern in repo
config.signing_secret Secret Never returned on GET Echoed in export
config.channel_name Setting Persist N/A
config.retry_policy Setting Persist N/A

Remediation matrix

Secret type Secure pattern Anti-pattern Severity Incident response
Bot token env:TEAM_CHAT_BOT_TOKEN Literal in YAML High Rotate token
Gateway auth GATEWAY_AUTH_TOKEN env Hardcoded in compose Critical Regenerate token
IMAP password Secret manager reference Plain in JSON POST Critical Force password reset
Webhook signing secret env indirection Logged in debug High Disable debug in prod
Search API key env:SEARCH_API_KEY Committed in example Medium Revoke key
Database URL env:DATABASE_URL Password in git Critical Rotate DB creds

Terminal evidence — expected

Static scan (representative):

$ rg "xoxb-|sk-[A-Za-z0-9]{20}" examples/
(no matches)
exit=0

Example registration payload (expected shape):

{
  "type": "team_chat",
  "config": {
    "bot_token": "env:TEAM_CHAT_BOT_TOKEN",
    "app_id": "1234567890"
  }
}

Runtime gateway log (expected):

Resolved TEAM_CHAT_BOT_TOKEN from environment
Persisted channel config (secret fields redacted)

Terminal evidence — unexpected

$ rg "xoxb-" examples/gateway/
examples/gateway/demo.yaml: bot_token: "xoxb-123-abc..."
→ critical finding
GET /api/channels/abc
{
  "config": {"api_key": "sk-live-..."}
}
→ secret exfiltration via admin API

How to fix (code and examples)

Layer Change File patterns
Examples Replace literals with env:VAR syntax examples/**, bot samples
Samples Add .example templates; gitignore live configs gateway compose, helm values
Docs Show redacted payloads only docs/channels/*
Product (follow-up) Reject known secret keys on persist channel service handler
CI Secret scan gate on PR workflow with rg/trufflehog
Example patch (conceptual)
- "bot_token": "xoxb-demo-token"
+ "bot_token": "env:TEAM_CHAT_BOT_TOKEN"
Gateway startup validation (recommended)
def resolve_config_value(raw: str) -> str:
    if raw.startswith("env:"):
        name = raw[4:]
        value = os.environ.get(name)
        if not value:
            raise ConfigurationError(f"Missing environment variable {name}")
        return value
    if looks_like_secret(raw):
        raise ConfigurationError("Literal secrets cannot be loaded from config files")
    return raw

PR review checklist

Check Pass Fail
New example files Placeholders only Contains sk-/token prefixes
YAML samples .example naming config.yaml tracked
Tests Use fake tokens Real credentials
Logs Redact secrets Print token on debug

Acceptance criteria

  • Scan clean for high-confidence secret patterns in examples tree
  • Secure reference example per major channel integration type
  • Golden path operator doc references this policy
  • Security checklist item on gateway/channel PR template

Out of scope

  • Enterprise HSM integration guide
  • Full SOC2 control mapping

Engineering FAQ

Question Answer Verify with
env: prefix standard? Document in gateway config reference Docs PR
Kubernetes secrets? Mount as env — same as bare metal Helm example
Rotation procedure? Update secret store then rolling restart Runbook
Detect sk- in PR? CI rg step fails build Workflow log
Redact in logs? Gateway must never log resolved token Log review
UI shows secret? Mask on display; reveal requires admin UI audit
Export API? Strip secret fields or replace with REDACTED Integration test
Backup encryption? Infra concern — note in deployment guide Ops doc
Example tests fake tokens? Use xoxb-fake-test pattern only in tests/ Scan exclude
Third-party tutorials? Link official secure example Docs
Report leak? Rotate credential immediately Incident template
env var missing? Fail fast at startup with variable name Gateway log
Literal in migration? One-time scripts must read from env Migration review
Database password? Treat as secret class Classification table
Webhook URL secrets? Query params count as secrets Example JSON
Compliance scan tools? Optional trufflehog in CI Security team
Customer copy-paste? Examples must be safe verbatim UX review
Persist reference token? Product follow-up — store env:NAME only API design
Audit trail? Log channel create without values Log sample
Severity escalation? Any real token in git history — rotate + purge Security SOP

Operational runbook

Step Action Expected signal If fail
1 Run secret pattern scan on examples tree Zero hits Open remediation PR
2 Replace literals with env: references Diff clean Re-scan
3 Add gitignore for live configs Ignored paths Commit
4 Update channel registration doc Shows env pattern Review
5 Gateway code review for log redaction No token substrings Static review
6 Merge secure reference example per channel type Examples index updated Track in ticket
7 Enable CI scan workflow Red on new secret Branch protection
8 Train support on rotation SOP Playbook link Enablement

Evidence log template

Run Date Command Expected marker Unexpected marker
SEC-1 YYYY-MM-DD rg secret scan 0 matches Hit in examples
SEC-2 YYYY-MM-DD Register channel with env ref Persist redacted Plain token in GET
SEC-3 YYYY-MM-DD Gateway startup missing env Clear error Silent empty token

Engineering FAQ

Question Answer Verify with
Is env: enough for prod? Yes when combined with secret store injection K8s docs
Double encryption? Infra layer — not app matrix Ops
Token in issue attachments? Forbidden — use redacted snippets Support policy
Customer sent token in ticket? Force rotate + purge ticket Security
Hash secrets at rest? Product follow-up Roadmap
Audit export? Must strip secret keys Test
Dev laptops? Same rules — no exceptions Culture
Compose override files? gitignored Template
Screenshot redaction? Required in docs PR review Visual review
Third-party deps? Scan transitive example data CI

Secret asset inventory

Asset Storage Secret allowed? Rotation owner
Bot token Secret store → env Never on disk Operator
Gateway admin token Env at deploy Never in git Platform
IMAP credentials Secret manager Never in channel JSON Mail admin
Webhook HMAC Env Never logged Integrations
Database URL Env / vault Password not in repo DBA
Search API key Env Optional service Developer
Lingua principale
Python
Stelle
9.3k
Fork
1.5k
Merge medio
1g 5h
PR unite (30g)
520

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di MervinPraison/PraisonAI

Tutte le issue di MervinPraison/PraisonAI

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.