Outbound Secret Scrub

Never deliver a registered secret or a credential-shaped token to a chat user

Every reply, streamed draft, and proactive send is passed through a scrubber before it leaves the process — on by default, no config.

from praisonaiagents import Agent
from praisonai.bots import TelegramBot

# No configuration — every outbound reply is scrubbed by default.
agent = Agent(name="Ops", instructions="Answer questions.")
bot = TelegramBot(token="...", agent=agent)

import asyncio
asyncio.run(bot.start())
# A tool result containing sk-abc… or AKIA… is masked as [REDACTED]
# before the reply is sent to Telegram.

Quick Start

1. Zero config — scrubbing is on by default

   from praisonaiagents import Agent
   from praisonai.bots import TelegramBot
   
   agent = Agent(name="Ops", instructions="Answer questions.")
   bot = TelegramBot(token="...", agent=agent)
   
   import asyncio
   asyncio.run(bot.start())

   Registered gateway credentials and credential-shaped tokens are masked in every reply without any setup.

2. Opt out per bot

   bot._redact_secrets_outbound = False

   Disable the scrub for a single bot. Only do this when another layer upstream already guarantees no secret leaves.

3. Bring your own redactor (e.g. add PII)

   from praisonaiagents.secrets import redact_outbound
   
   class PIIRedactor:
       def redact(self, text: str) -> str:
           text = redact_outbound(text)          # keep the built-in secret scrub
           return text.replace("@example.com", "[EMAIL]")  # add your own policy
   
   bot._outbound_redactor = PIIRedactor()

   Inject a custom scrubber that wraps the core primitive and adds extra rules.

What Gets Masked

Two things are masked before a reply leaves the process: every value registered via register_secret_for_redaction (all resolved gateway credentials, masked by exact value) plus any token matching a narrow credential-shape pattern.

How It Works

The scrub runs after every MESSAGE_SENDING hook, so a hook cannot re-introduce a secret after your own logic runs.

Which Paths Are Covered

Every path that dispatches text to a chat user is scrubbed.

Custom Redactor

Inject an OutboundRedactor to add a policy the core scrub does not cover — PII, a company-internal token pattern, and so on.

from praisonaiagents.secrets import redact_outbound, OutboundRedactor

class MyRedactor:
    def redact(self, text: str) -> str:
        text = redact_outbound(text)                 # keep built-in secret scrub
        return text.replace("INTERNAL-", "[REDACTED]")  # your extra rule

bot._outbound_redactor = MyRedactor()

OutboundRedactor is a @runtime_checkable protocol with one method, redact(self, text: str) -> str. The injected redactor wins over the core primitive. It must return a str — any non-str return is ignored and the core redact_outbound runs instead.

Opt-Out

Turn the scrub off for a single bot by setting one attribute.

bot._redact_secrets_outbound = False

Ordinary Text Is Unchanged

The scrub is additive — absent a leak, ordinary text passes through untouched.

Idempotency & Failure Modes

Scrubbing is idempotent — running it on already-scrubbed text is a no-op, so overlapping seams (finalize + reply hook) never double-mask. It is also best-effort: a scrubber exception is caught at every seam and the original text is delivered rather than dropped, so a bug in a custom redactor can never block delivery.

Relationship to the Inbound Gate

Inbound and outbound are symmetric. The Inbound Message Gate filters what reaches the agent through MESSAGE_RECEIVED; the outbound scrub filters what leaves the agent on the reply path. Together they bracket the agent on both sides.

Best Practices

Related