Skip to content

FEAT: Add PigpenConverter on a shared character-substitution base - #4446

Open
Roman Lutz (romanlutz) wants to merge 7 commits into
microsoft:mainfrom
romanlutz:gap1-pigpen
Open

Roman Lutz (romanlutz) wants to merge 7 commits into
microsoft:mainfrom
romanlutz:gap1-pigpen

Conversation

@romanlutz

@romanlutz Roman Lutz (romanlutz) commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Adds a first-class PigpenConverter for the Pigpen (Freemason's / Masonic) cipher — a geometric monoalphabetic substitution where each letter becomes the fragment of the grid surrounding its cell. Classical ciphers as a jailbreak vector: CipherChat, Yuan et al., arXiv:2308.06463.

Shared base. Per design discussion, the per-character substitution engine (the table, deterministic/random selection, and validation) is extracted from LeetspeakConverter into a shared abstract base, _CharacterSubstitutionConverter (on WordLevelConverter). LeetspeakConverter and PigpenConverter are thin named members — the same pattern as the base16/32/64 family on _ByteEncodingConverter. Mirror/upside-down are intentionally out of scope (they also reverse the whole string).

  • LeetspeakConverter's public behaviour and identifier are preserved byte-for-byte (it keeps its own __init__/_build_identifier, including the "default table isn't hashed" semantics), verified across default/custom/empty/case modes.
  • The base is abstract, so only the named members are discoverable converters.
  • Pigpen moves from a LeetspeakConverter(custom_substitutions=...) config to PigpenConverter(); the Encoding scenario registers it directly.

Glyph correctness. The table maps each letter to the lines the key actually draws around its cell (A-I ┘⊔└⊐□⊏┐⊓┌, J-R the same with a combining dot, S-V the saltire ▽▷◁△, W-Z with a dot), fixing the earlier mirrored mapping (cat previously encoded as the key's git). A test pins the converter to an independent transcription of the key.


gap-1 converter series: #4441 #4442 #4443 #4444 #4445 #4446 #4447 #4450 #4451 #4452 #4454 #4455 #4456 #4457 #4458 (#4448, #4449 merged)

🤖 Generated with Claude Code

Copilot AI balanced review requested due to automatic review settings November 19, 2026 23:36

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The published notebook lacks the Pigpen import, example, and rendered output, leaving readers without the new example and violating the requirement to keep paired documentation files synchronized.

1 open issue
What changed in this PR

Adds PigpenConverter to PyRIT’s text-obfuscation converters and integrates it into the garak Encoding scenario.

Changes:

  • Implements a case-insensitive Unicode approximation of the Pigpen cipher.
  • Exports the converter and registers it as an ALL-only encoding technique.
  • Adds converter tests, updates scenario expectations, and adds a Python documentation example.
File Description
tests/​unit/​scenario/​garak/​test_encoding.py Updates technique counts and ALL-only expectations.
tests/​unit/​converter/​test_pigpen_converter.py Tests mappings, case handling, passthrough, and input validation.
pyrit/​scenario/​scenarios/​garak/​encoding.py Registers the Pigpen encoding technique.
pyrit/​converter/​pigpen_converter.py Implements the Unicode Pigpen converter.
pyrit/​converter/​__init__.py Adds the public lazy export.
doc/​code/​converters/​1_text_to_text_converters.py Adds a Pigpen conversion example.

Review effort: Balanced

@richlundeen Richard Lundeen (richlundeen) left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Withdrawn: this earlier suggestion to drop the named converter in favor of configuring an existing one no longer applies. Named converters are welcome; see the current review.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Source review of this head: one P1 and three P3 findings, inline. The notebook pairing is already covered by the open thread on 1_text_to_text_converters.py:87.

Comment thread pyrit/converter/pigpen_converter.py Resolved
Comment thread pyrit/converter/pigpen_converter.py Resolved
@romanlutz

Copy link
Copy Markdown
Contributor Author

Reworked per your suggestion: dropped PigpenConverter; the pigpen technique is now LeetspeakConverter(custom_substitutions=_PIGPEN_SUBSTITUTIONS) with the documented Pigpen glyph table retained as that constant, plus a focused test. Thanks!

@romanlutz Roman Lutz (romanlutz) changed the title FEAT: Add PigpenConverter (pigpen converter) FEAT: Add pigpen Encoding technique via LeetspeakConverter Nov 20, 2026
Per review (reuse and compose before adding): keep the pigpen technique but implement it as LeetspeakConverter(custom_substitutions=<pigpen glyph table>) instead of a dedicated PigpenConverter class. The documented Pigpen key is retained as _PIGPEN_SUBSTITUTIONS.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Addresses the P1 on microsoft#4446: _PIGPEN_SUBSTITUTIONS picked each glyph by its Unicode
stroke directions, which draws the mirror of the key's shape, so 24 of 26 letters
were wrong (e.g. 'a' gave the key's I and 'e' a cross instead of a closed box).
A target that knows Pigpen would read 'cat' as 'git', and DecodingScorer would
record a non-decode.

Remap each letter to the lines the key draws around its grid cell: A-I on the
tic-tac-toe grid (┘⊔└⊐□⊏┐⊓┌), J-R the same with a combining dot, S-V on the
saltire (▽▷◁△), W-Z the same with a dot. Replace the self-checking test with one
that pins the table to an independent transcription of the key, so a mirrored or
swapped glyph fails.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The Encoding scenario's ALL aggregate now has 20 techniques; the scanner guide
still said 18 and ended at Bifid, omitting ColumnarTransposition (already on main)
and this PR's Pigpen. Update both the paired .py and .ipynb.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
# Conflicts:
#	doc/scanner/garak.ipynb
#	doc/scanner/garak.py
#	pyrit/scenario/scenarios/garak/encoding.py
#	tests/unit/scenario/garak/test_encoding.py
Per design discussion, extract the per-character substitution engine from
LeetspeakConverter into a shared abstract base (_CharacterSubstitutionConverter,
on WordLevelConverter): the table, deterministic/random selection, and validation.
LeetspeakConverter and the new public PigpenConverter are thin named members.
Mirror/upside-down (whole-string transforms) are intentionally out of scope.

Pigpen moves from a LeetspeakConverter(custom_substitutions=...) config to a
first-class PigpenConverter, mirroring the base16/32/64 decision. The glyph table
(the corrected key mapping) lives with the converter; the Encoding scenario now
registers PigpenConverter().

LeetspeakConverter's public behaviour and identifier are preserved byte-for-byte
(it keeps its own __init__ and _build_identifier, including the default-table-not-
hashed semantics); verified across default/custom/empty/case modes. The base is
abstract so only the named members are discoverable converters.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@romanlutz Roman Lutz (romanlutz) changed the title FEAT: Add pigpen Encoding technique via LeetspeakConverter FEAT: Add PigpenConverter on a shared character-substitution base Nov 21, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants