Skip to content

REFACTOR: Add shared Polybius-square helper; add Playfair/FourSquare/Trifid/TwoSquare - #4458

Draft
Roman Lutz (romanlutz) wants to merge 2 commits into
microsoft:mainfrom
romanlutz:gap1-polybius-square
Draft

Roman Lutz (romanlutz) wants to merge 2 commits into
microsoft:mainfrom
romanlutz:gap1-polybius-square

Conversation

@romanlutz

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

Copy link
Copy Markdown
Contributor

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

…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>

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

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

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.

2 participants