Trojan Source is the name for a class of attacks in which Unicode control characters reorder how source code looks on screen without changing how the compiler reads it. This page looks at the problem from the detection side: what a scanner can surface, how a review process should use it, and which parts still need a human eye.
What is Trojan Source?
Trojan Source is a way of hiding logic in plain sight. It leans on Unicode bidirectional (BiDi) control characters — the same mechanism that lets right-to-left languages such as Arabic and Hebrew sit on the same line as left-to-right text. Inside a source file, a character such as U+202E Right-to-Left Override can flip the visual order of everything that follows it. The compiler still reads the file in its stored logical order, but a person reading the same file sees the characters in a different order.
Because the bytes and the picture disagree, a block of code can look harmless on screen while the underlying file contains something else. That gap between what is displayed and what is executed is the heart of the attack. For the concept and a worked example, see the companion page Trojan Source: When Text Order Lies.
What a Trojan Source scanner looks for
A scanner does not try to guess intent. It looks for the specific, enumerable characters that make this class of trick possible and reports each one with its position. The signals worth flagging are:
- Bidirectional override and embedding controls (U+202A–U+202E and the isolates U+2066–U+2069) — the core of a Trojan Source payload.
- The directional markers U+200E Left-to-Right Mark, U+200F Right-to-Left Mark, and U+061C Arabic Letter Mark, which can open, close, or neutralize a directional run.
- Invisible characters nearby, such as zero-width spaces (U+200B) and word joiners (U+2060), often used to pad or disguise a run.
- Directional controls that appear where they have no legitimate reason to be: inside an identifier, a string literal, a comment, a URL, or a file path.
Each match is reported with its code point, its line, and the surrounding text, so a finding is a location to inspect rather than an automatic verdict.
How a code audit actually goes
Detection feeds a process. A reasonable order of operations is:
- Run the scan over the file, or over the diff you are reviewing, so the check is scoped to what changed.
- Sort the findings by severity and read from the top, since override characters outrank cosmetic ones.
- For every bidirectional finding, jump to the reported position and read the raw bytes in an editor that displays control characters.
- Compare the visual order against the logical order, and confirm which one the compiler will use.
- Read the surrounding logic, not just the flagged line, to judge whether the behaviour matches the rest of the code.
- Decide the outcome: remove the control characters, or, if the direction is genuinely needed for bilingual content, keep it and leave a note for the next reviewer.
If the finding came from a pull request, the same steps apply to the diff. The most useful change is to wire the scan into the pipeline so it runs on every change instead of once.
What a reviewer should still check by hand
A scanner catches characters, not motives. Some parts of the job cannot be automated, and those are where a human adds the most value:
- Whether the file you are reading is really the committed version, and not a locally edited copy that differs from what the scanner saw.
- Whether the logic around a flagged line holds up in context, including error handling and boundary checks.
- Whether removing a control character would alter legitimate bilingual content the file was meant to contain.
- Whether the same pattern appears in generated files, lockfiles, or vendored code, where a human is even less likely to look.
Scanners are a tripwire, not a verdict
A clean scan is not proof that code is safe, and a dirty scan is not proof of an attack. Bidirectional characters have legitimate uses, and no scanner can tell a bilingual comment from a payload on the strength of a code point alone. What a scanner does is shrink the search space: instead of reading thousands of lines hoping to notice something invisible, you get a short list of exact positions to review.
Related reading
Bidirectional controls are not the only Unicode trick that can make two strings look identical while having different bytes. To understand the characters themselves — what they are, which scripts need them, and how they affect display — see BiDi / Bidirectional Text Detector. For the encoding angle, see Unicode Normalization in Plain English.