Guide · Secret scanning

How to catch leaked API keys before you share what your agent made

AI agents paste real credentials into example configs, error logs and quick sanity dumps all the time — and they rarely flag it. If that output becomes a shared link, the key goes with it. Here's how to catch a leaked secret before anyone can open the page.

When you publish a document with freo.cloud, the file is scanned for leaked credentials on the way in — before it reaches storage or a viewer. High-confidence matches (AWS, OpenAI, Anthropic, GitHub and Stripe keys, JWTs, connection strings) and dangerous filenames like .env or *.pem are blocked: the publish is refused, and your agent gets a masked preview plus a fix hint so it can strip the key and retry.

On a chat app like Claude.ai or ChatGPT instead of a coding agent? Connect the MCP server with one-click OAuth (no token) — then the same "just ask it to publish" flow applies.

Why AI output leaks secrets in the first place

Agents are helpful to a fault. Ask one to document a setup and it will happily fill the example config with the real value it can see in your environment. Ask it to debug a failing call and it pastes the full request — headers, tokens and all — straight into the log it hands back. A .env gets echoed "for completeness." A connection string with the live password lands in a troubleshooting note. None of this is malicious; it's just what a model does when it optimises for a clear, copy-pasteable answer.

The trouble starts at the last step. That output becomes a report, a dashboard, an HTML page — and then a link you send to a client or a colleague. The moment it's shared, so is the key. And by then the leak is out of your hands: you can rotate the credential, but you can't un-send the URL.

What freo blocks, and what it just warns about

The scan sorts findings into two buckets. High-confidence matches — the ones that are almost never a coincidence — stop the publish outright. Lower-confidence ones are surfaced but let through, because a hard block on a maybe would cost you more than it saves.

• →Blocked — credential patterns: AWS access keys, OpenAI and Anthropic keys, GitHub tokens, Stripe keys, JWTs, and database connection strings. These have distinctive shapes, so a match is a strong signal.
• →Blocked — dangerous filenames: .env, id_rsa, *.pem, *.key and their kin. If your agent tried to publish one of these, it almost certainly didn't mean to.
• →Warned, not blocked: high-entropy strings that look like they could be a secret, and personal data (PII). These are logged so you can review them, but they don't stop the publish — false positives here are common enough that blocking would be more noise than protection.

What happens when a secret is found

A block isn't a silent failure. When a high-confidence match trips the scan, the publish is refused before the file is stored — nothing is written, nothing is served, no link exists yet. Your agent gets a specific reply back, not a generic error: what type of secret was found, a masked preview so you can identify which value it is without re-exposing it, and a short remediation hint. In practice the agent reads that, strips or replaces the offending value, and re-publishes — usually without you having to intervene at all.

Overriding a false positive

Sometimes the "secret" is on purpose — a documented example with a placeholder token, or a tutorial showing the shape of a key. For those you can consciously override a specific finding type per publish, rather than flipping a global "turn scanning off" switch. Only do it when you're certain the match is a placeholder: if there's any doubt a value is real, treat it as real and let the block do its job — an override on a live key defeats the point the moment the link is out.

It's defence in depth, not a promise

Be clear-eyed about what this is. The scan is pattern-based and currently in beta: it recognises the credential formats and filenames that leak most often, and it catches the common cases well. It is not a guarantee. A secret in an unusual format, a home-rolled token, or a key split across lines can slip past — no pattern matcher catches everything.

So treat it as one layer, not the whole wall. It's a strong last check that stops the obvious, expensive mistakes before they ship — but you should still review anything sensitive before you share it, and pair the scan with tight access control so that even a clean document only reaches the people you meant it for.