Repository navigation
REFACTOR: Add shared Polybius-square helper; add Playfair/FourSquare/Trifid/TwoSquare - #4458
Draft
Roman Lutz (romanlutz) wants to merge 2 commits into
Draft
Roman Lutz (romanlutz) wants to merge 2 commits into
Roman Lutz (romanlutz) wants to merge 2 commits into
Conversation
…Trifid/TwoSquare Introduces a shared _polybius_square helper (keyed-alphabet build + PolybiusSquare coordinate lookup), migrates the existing Bifid onto it, and adds PlayfairConverter, FourSquareConverter, TrifidConverter and TwoSquareConverter. Four-square/Trifid/Two-square are registered as ALL-only garak Encoding techniques (Playfair is a cipher, not an encoding technique). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This was referenced Nov 20, 2026
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Some encoders lose payload data or mishandle filler characters, decoding instructions omit necessary cipher details, conversions can block the event loop, and expanding ALL breaks existing run resumes.
6 open issues
Avoid synchronous YAML loading on the async conversion path · New Preserve configured filler characters during case conversion · New Document the alternate-filler rule in decoding instructions · New Restore saved concrete selections when resuming ALL runs · New Include cipher parameters in decoding instructions · New Use lossless encodings for payloads with punctuation and digits · New
What changed in this PR
This PR expands PyRIT’s classical-cipher converters and shares their alphabet and grid logic through a private Polybius helper.
Changes:
- Add Playfair, Four-square, Trifid, and Two-square converters; refactor Bifid to reuse shared utilities.
- Add Four-square, Trifid, and Two-square to Garak’s ALL-only encoding techniques.
- Add Playfair description framing, unit coverage, registry integration, and usage examples.
| File | Description |
|---|---|
tests/unit/scenario/garak/test_encoding.py |
Update technique counts and ALL-only expectations. |
tests/unit/registry/test_converter_registry.py |
Account for Four-square key parameters. |
tests/unit/registry/converter_identifier_samples.py |
Add identifier parameter samples. |
tests/unit/converter/test_two_square_converter.py |
Cover vectors, round-trips, padding, and validation. |
tests/unit/converter/test_trifid_converter.py |
Cover vectors, periods, fillers, and validation. |
tests/unit/converter/test_polybius_square.py |
Test alphabet helpers and square lookups. |
tests/unit/converter/test_playfair_converter.py |
Cover cipher rules, framing, and validation. |
tests/unit/converter/test_four_square_converter.py |
Cover vectors, normalization, and validation. |
tests/unit/backend/test_converter_service.py |
Supply required Four-square construction parameters. |
pyrit/scenario/scenarios/garak/encoding.py |
Register three additional encoding techniques. |
pyrit/datasets/converters/playfair_description.yaml |
Add Playfair instructions and example framing. |
pyrit/converter/two_square_converter.py |
Implement vertical Two-square encoding. |
pyrit/converter/trifid_converter.py |
Implement cube-based Trifid encoding. |
pyrit/converter/playfair_converter.py |
Implement Playfair encoding and optional framing. |
pyrit/converter/four_square_converter.py |
Implement keyed Four-square encoding. |
pyrit/converter/bifid_converter.py |
Replace local square logic with shared utilities. |
pyrit/converter/_polybius_square.py |
Add shared alphabet, sanitization, and grid helpers. |
pyrit/converter/_cipher_description.py |
Add reusable cipher-description rendering. |
pyrit/converter/__init__.py |
Lazily export all four new converters. |
doc/code/converters/1_text_to_text_converters.py |
Add examples for the new converters. |
Review effort: Balanced
| """ | ||
| if not append_description: | ||
| return encoded | ||
| template = SeedPrompt.from_yaml_file(pathlib.Path(CONVERTER_SEED_PROMPT_PATH) / f"{yaml_stem}_description.yaml") |
| Returns: | ||
| str: The encoded uppercase cipher text. | ||
| """ | ||
| cleaned = [char for char in text.upper() if char in self._symbol_to_coords] |
Comment on lines
+31
to
+32
| '{{ padding_char }}' used as the filler letter that splits doubled letters and pads an | ||
| odd-length message. Each pair of letters is enciphered by one of three rules depending on |
Comment on lines
+133
to
+135
| FourSquare = ("four_square", set[str]()) | ||
| Trifid = ("trifid", set[str]()) | ||
| TwoSquare = ("two_square", set[str]()) |
Comment on lines
+323
to
+325
| ([FourSquareConverter(top_right_key="example", bottom_left_key="keyword")], "four_square", "four_square"), | ||
| ([TrifidConverter()], "trifid", "trifid"), | ||
| ([TwoSquareConverter()], "two_square", "two_square"), |
Comment on lines
+323
to
+325
| ([FourSquareConverter(top_right_key="example", bottom_left_key="keyword")], "four_square", "four_square"), | ||
| ([TrifidConverter()], "trifid", "trifid"), | ||
| ([TwoSquareConverter()], "two_square", "two_square"), |
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

Part of the gap-1 converter series (splitting the esoteric cipher / encoder set into per-converter and per-base PRs). This PR introduces a shared base/helper and the converters built on it; CI-validated locally (unit + garak Encoding + identifier-contract tests).
Sibling PRs will be cross-linked once the series is open.
🤖 Generated with Claude Code
gap-1 converter series — splitting the esoteric cipher / encoder set into reviewable PRs (open each independently; they touch the same four registration files, so later ones rebase as earlier ones merge):