Skip to content
agentscope-ai-javaPublic

About

A logging.Formatter that escapes control characters so a logged value cannot forge a log line.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

Repository files navigation

logsafe

A logging.Formatter that escapes control characters, so a value you log can't forge a fake log line.

The problem

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.

Why this isn't a universal gap

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, default Formatter: vulnerable — shown above.
  • pino (Node): safe by default. Its output is JSON.stringify-encoded, and JSON.stringify escapes \n as \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 (slog uses strconv.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.

Why not just strip newlines yourself?

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.

Install

pip install logsafe

Python >= 3.11. Zero runtime dependencies — standard library only.

Use

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 characters

install() 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).

What gets escaped, and how

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.)

Scope: values, not the whole line

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/datefmt template — 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-line fmt.
  • exc_info / stack_info tracebacks — 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.

Tracebacks: a deliberate, documented trade-off

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.

API

  • SafeFormatter(fmt=None, datefmt=None, style="%", validate=True, *, defaults=None) — drop-in subclass of logging.Formatter, same constructor signature.
  • install(logger=None, *, handler=None, fmt=None, datefmt=None, style="%") — installs SafeFormatter on a logger's handlers (default: root logger) or on a single handler, preserving existing fmt/datefmt where it can.
  • escape_control_chars(value: str) -> str — the escaping primitive, if you want to apply it yourself to a value before passing it as extra=.

What it does not do

  • 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; logsafe has nothing to add there.
  • It does not sanitize exception messages inside tracebacks — see "Tracebacks" above.
  • It does not wrap arbitrary custom Formatter subclasses. install() can only safely reuse fmt/datefmt from a plain logging.Formatter (or a handler with no formatter set); for anything else it falls back to plain defaults, discarding that subclass's custom rendering — see the install() 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.

Develop

python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'
.venv/bin/python -m pytest -q
.venv/bin/python -m mypy --strict src tests

Evidence

examples/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.py

License

MIT

About

A logging.Formatter that escapes control characters so a logged value cannot forge a log line.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages