A logging.Formatter that escapes control characters, so a value you log
can't forge a fake log line.
Python's stdlib logging, with the default Formatter, does not escape
control characters in logged values. If an attacker controls any field you
log — a username, a User-Agent, a search query — and that value contains a
newline followed by text shaped like a log line, the result is a second,
fully fabricated log entry that is indistinguishable from a real one once it
reaches a text sink (a file, stdout, a syslog stream).
import logging, sys
logger = logging.getLogger("auth")
logger.addHandler(logging.StreamHandler(sys.stdout))
logger.handlers[0].setFormatter(
logging.Formatter("%(asctime)s %(levelname)s %(name)s: %(message)s")
)
username = "bob\n2026-09-27 12:00:00 INFO auth: bob logged in successfully (forged, not real)"
logger.info("login attempt for user=%s", username)Real output, one call, two lines (from examples/demo.py, section 1):
2026-09-27 08:09:50 INFO demo.vulnerable: login attempt for user=bob
2026-09-27 12:00:00 INFO auth: bob logged in successfully (forged, not real)
The second line was never logged by anyone — it's inside the first call's
username argument. Anything downstream that greps, alerts on, or feeds this
into a SIEM sees a legitimate-looking "successful login" event that never
happened. This is classic log injection / log forging (CWE-117): an attacker
who controls one logged field can fabricate entries, hide the trace of a real
attack among noise, or poison alerting rules built on log line contents.
This is specifically a Python stdlib text-formatter problem (and the equivalent pattern in Node's common text-format loggers), not a universal logging flaw. Re-verified directly, not assumed:
- Python stdlib
logging, defaultFormatter: vulnerable — shown above. pino(Node): safe by default. Its output isJSON.stringify-encoded, andJSON.stringifyescapes\nas\n(the two-character sequence) inside the JSON string, so an embedded newline can't break out of the value's quotes.- Go's
log/slog,TextHandler: already safe. It quotes any value containing a control character (slogusesstrconv.Quote-style encoding), so Go's own stdlib got this right by default.
The pattern that's actually vulnerable is plain-text, printf-style
formatting that concatenates interpolated values directly into a line with
no escaping and no quoting — which is exactly what Python's default
Formatter does. If your service already logs structured JSON (Python's
json.dumps, structlog's JSON renderer, python-json-logger, etc.), this
package has nothing to add: JSON string-escaping already closes this gap the
same way pino does. logsafe is for the (extremely common) case of plain
text log lines going through logging.Formatter.
You could, at every call site, remember to sanitize every value before logging it. In practice nobody does this consistently — it's the same "remember to escape it" trap as SQL injection before parameterized queries. The fix that actually holds is one applied at the formatter, once, for every handler, so it doesn't depend on every call site getting it right.
pip install logsafePython >= 3.11. Zero runtime dependencies — standard library only.
import logging
from logsafe import SafeFormatter
logger = logging.getLogger("auth")
handler = logging.StreamHandler()
handler.setFormatter(SafeFormatter("%(asctime)s %(levelname)s %(name)s: %(message)s"))
logger.addHandler(handler)
logger.info("login attempt for user=%s", untrusted_username)Or, to patch every handler already configured on a logger (default: the root logger) in one call, without touching each handler's setup code:
import logging
from logsafe import install
logging.basicConfig(format="%(asctime)s %(levelname)s: %(message)s")
install() # root logger's handlers now escape control charactersinstall() preserves each handler's existing fmt/datefmt when it can
(see the docstring for the one case it can't: a handler already using a
custom Formatter subclass, e.g. a JSON formatter — which doesn't need this
in the first place, per above).
Backslash, the C0 control characters (0x00-0x1F), DEL (0x7F), and the
Unicode line/paragraph separators U+2028 / U+2029 (not ASCII, but treated
as line breaks by some log parsers and terminal-adjacent tools). Everything
else — all ordinary Unicode: accents, CJK, emoji, right-to-left text — passes
through completely unchanged.
The escaping is legible and reversible: a newline becomes the two characters
\n (backslash then the letter n), not a placeholder or a dropped
character, so the log stays readable and a human (or a script) can tell
what was really in the value. Backslash itself is escaped first (\ →
\\), which is what makes it reversible: without that, a value containing
the literal two characters \n would be indistinguishable, after escaping,
from a value containing an actual newline character.
| Input character | Escaped as |
|---|---|
\n |
\n |
\r |
\r |
\t |
\t |
\ |
\\ |
\x00 |
\0 |
other C0 / DEL |
\xHH |
U+2028 / U+2029 |
/
|
Same call as above, through SafeFormatter instead of the default
Formatter — real output, one line (examples/demo.py, section 2):
2026-09-27 08:09:50 INFO demo.safe: login attempt for user=bob\n2026-09-27 12:00:00 INFO auth: bob logged in successfully (forged, not real)
The forged suffix is now visibly part of the username value, not a second
log line. (examples/demo.py runs both of the above side by side — see
"Evidence" below for the actual command and output.)
SafeFormatter escapes the message (record.msg and record.args —
covering both logger.info("user %s", name) lazy formatting and
logger.info(f"user {name}") eager formatting) and any non-standard
extra attribute that's a string (logger.info(msg, extra={"user": name})
interpolated via a custom %(user)s format string). It deliberately does
not escape:
- The formatter's own
fmt/datefmttemplate — the literal text around%(message)s, the timestamp, the level name. That's operator-configured, not attacker-controlled, and escaping the whole rendered line would mean escaping the formatter's own intentional structure, including any newlines you deliberately put in a multi-linefmt. exc_info/stack_infotracebacks — see below.
This was a deliberate choice between two designs: escape the whole
formatted line (simple, but wrong — it would mangle a deliberately
multi-line fmt or traceback), versus escape only the values an attacker
can actually influence (harder, but correct). SafeFormatter does the
latter, by escaping on a copy of the LogRecord before handing it to
logging.Formatter's own format()/formatMessage(), rather than
post-processing the rendered string.
A traceback is legitimately multi-line. If SafeFormatter escaped the
exc_info-derived traceback text the same way it escapes the message, every
newline in every stack trace would come out as literal \n, turning a
readable multi-line trace into an unreadable wall of text. So tracebacks are
appended unescaped, exactly like stock logging.Formatter does. Real output
(from examples/demo.py, section 3):
2026-09-27 08:09:50 ERROR demo.traceback: request failed for user=carol\nFAKE injected line
Traceback (most recent call last):
File ".../examples/demo.py", line 67, in demo_traceback
raise ValueError("could not parse request")
ValueError: could not parse request
(the local absolute path in that File "..." line is trimmed above; everything else is verbatim.)
The message line is escaped (carol\nFAKE injected line stays on one
line); the traceback below it keeps its real newlines and stays readable.
Residual risk, stated plainly: if an attacker controls the message of
an exception you raise and log with exc_info=True, that message is
rendered as part of the traceback text (e.g. the ValueError: <message>
line) and is not escaped by SafeFormatter, since it comes from
traceback.format_exception, not from record.msg/args. If untrusted
input can reach an exception message in your codebase, that's a second,
narrower injection surface this package does not close. Sanitize values
before they go into exception messages if that's a path you're worried
about, or treat traceback text as inherently less trustworthy than the
structured message line above it.
SafeFormatter(fmt=None, datefmt=None, style="%", validate=True, *, defaults=None)— drop-in subclass oflogging.Formatter, same constructor signature.install(logger=None, *, handler=None, fmt=None, datefmt=None, style="%")— installsSafeFormatteron a logger's handlers (default: root logger) or on a single handler, preserving existingfmt/datefmtwhere it can.escape_control_chars(value: str) -> str— the escaping primitive, if you want to apply it yourself to a value before passing it asextra=.
- It does not make JSON/structured logging safer — it doesn't need to.
If you already log structured JSON,
json.dumps's own string escaping already prevents this;logsafehas nothing to add there. - It does not sanitize exception messages inside tracebacks — see "Tracebacks" above.
- It does not wrap arbitrary custom
Formattersubclasses.install()can only safely reusefmt/datefmtfrom a plainlogging.Formatter(or a handler with no formatter set); for anything else it falls back to plain defaults, discarding that subclass's custom rendering — see theinstall()docstring. - It is not an HTML/shell/SQL escaper. It only targets the specific character set that can forge a fake line in a text log sink.
- It does not rate-limit or deduplicate logs, and isn't a general log sanitization/redaction (e.g. PII scrubbing) tool.
python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'
.venv/bin/python -m pytest -q
.venv/bin/python -m mypy --strict src testsexamples/demo.py runs the vulnerable and safe cases plus the traceback
case, for real, and prints the actual output — the exact text pasted above
under "The problem" and "Tracebacks" came from running:
.venv/bin/python examples/demo.pyMIT