FEAT add CodeAttackConverter (closes #1945)

[Utkarsh Bahuguna (u7k4rs6)]

Closes #1945.

Summary

Implements CodeAttack (Ren et al., ACL 2024, arXiv:2403.07865), which reformulates a harmful query as a code-completion task. The query is encoded into a data-structure initialization sequence inside a partial code template with a decode() stub, and the target is asked to complete the code. Because the intent is expressed as a programming task rather than a natural-language request, safety training keyed to natural language triggers less reliably. Black-box, no compute requirements.

Two notes for review (deltas from the issue)

1. Encoding is word-by-word, not character-by-character. The issue described it as char-by-char (from the paper abstract), but the reference implementation (renqibing/CodeAttack) splits on whitespace and hyphens via regex, with character-level only as a fallback for single-token inputs. I matched the reference code. One consequence: the two token-splitting encodings normalize separators. PYTHON_LIST calls str.split(), so it collapses any run of whitespace and drops leading and trailing whitespace, though hyphens survive inside tokens. PYTHON_STACK does the same and additionally consumes hyphens as delimiters, and reverses token order. The three string encodings (PYTHON_STRING, CPP, GO) embed the prompt as a single literal and round-trip byte-identically. The converter docstring spells out which inputs are lossless under which encoding.

2. Eight templates, not five. The issue scoped five (one per language), but the reference ships eight: the three Python types each have a base and a _plus verbose variant, and cpp and go have no verbose variant upstream. I included all eight to match the reference. Happy to drop the three _plus files if you would rather keep it to five.

Design

• CodeAttackConverter in pyrit/converter/code_attack_converter.py. It encodes the prompt into a data-structure initialisation sequence and renders a partial code template with a decode() stub. It is a standalone Converter and composes through the normal converter pipeline.

• Template selection is the CodeAttackConverter.Template enum, which has eight members:

  Member	Template file
  PYTHON_STACK	code_attack_python_stack
  PYTHON_STACK_VERBOSE	code_attack_python_stack_plus
  PYTHON_LIST	code_attack_python_list
  PYTHON_LIST_VERBOSE	code_attack_python_list_plus
  PYTHON_STRING	code_attack_python_string
  PYTHON_STRING_VERBOSE	code_attack_python_string_plus
  CPP	code_attack_cpp
  GO	code_attack_go

  The default is PYTHON_STACK_VERBOSE. A pathlib.Path can be passed instead to supply a custom template file.

• Encoding is a separate axis from the template. CodeAttackConverter.Encoding is a new public enum with five members: PYTHON_STACK, PYTHON_LIST, PYTHON_STRING, CPP, GO. For a built-in Template the matching encoding is derived automatically and does not need to be passed. For a pathlib.Path it is required, because the data structure cannot be inferred from a custom file; passing a Path without encoding= raises ValueError rather than silently defaulting.

• Eight seed prompts in pyrit/datasets/converters/, matching the CodeChameleon convention:
  code_attack_python_stack.yaml, code_attack_python_stack_plus.yaml,
  code_attack_python_list.yaml, code_attack_python_list_plus.yaml,
  code_attack_python_string.yaml, code_attack_python_string_plus.yaml,
  code_attack_cpp.yaml, code_attack_go.yaml.

• No attack class. Per review feedback the earlier CodeAttackAttack subclass was dropped, and the technique is registered as the code_attack factory in pyrit/setup/initializers/techniques/core.py, wiring the converter onto PromptSendingAttack.

Tests

63 unit tests in tests/unit/converter/test_code_attack_converter.py, covering per-template rendering, base vs _plus variants, word-recovery round-trips, separator normalization, empty, special-character and long prompts, custom pathlib.Path templates, unsupported input types, and identifier construction.

Factory coverage is split across two files. TestCodeAttackTechnique in tests/unit/setup/techniques/test_core_techniques.py holds the focused wiring tests (2): one asserting the factory shape (attack class, tags, description, and the single wired CodeAttackConverter with its template and encoding), and one asserting the wired converter actually encodes the objective. It sits next to the existing flip technique tests, which is where this repo keeps per-technique factory tests. Separately, tests/unit/setup/test_technique_initializer.py contributes the registry-level check, where code_attack is added to CORE_TECHNIQUE_NAMES and asserted against the built factory set in six places.

Two documentation surfaces:

• doc/code/converters/1_text_to_text_converters.py, section 1.2 Obfuscation Converters, next to CodeChameleon. The converter is template-based and runs offline, so the cell carries real executed output.
• The Code section in doc/code/executor/1_single_turn.py, showing the converter applied through AttackConverterConfig.

The ren2024codeattack entry in doc/references.bib cites the published ACL 2024 Findings paper.

Review round 2

• Language-aware string-literal escaping. All five encoders used json.dumps() with the default
  ensure_ascii=True, so a non-BMP character became a surrogate pair (\ud83d\ude00). Python evaluates that
  to two lone surrogates, and Go and C++ reject surrogate escapes outright, so emoji input produced code that
  would not compile. The encoders now share one escaping helper that emits literal UTF-8 and escapes only
  backslash, double quote and control characters. C++ uses three-digit octal for control characters, since its
  hex escapes consume an unbounded run of hex digits and would swallow a following literal digit. Verified by
  compiling the generated C++ and Go under -Wall -Wextra -Werror and go vet, then asserting byte-identical
  round-trips for emoji, newline, tab, backslash, double quote, control and DEL input.

• Template loaded and validated in __init__. SeedPrompt.from_yaml_file() moved out of convert_async
  and is cached on the instance, so it no longer parses YAML synchronously on every conversion and a missing or
  malformed custom file fails at construction. Construction also rejects a template whose body never references
  wrapped_input, which previously rendered a constant string and silently discarded the objective.

• Content-based identifier. _build_identifier() no longer embeds an absolute template path, which differed
  across worktrees and did not change when a custom file's contents changed. It now reports the stable enum name,
  a sha256[:16] of the loaded template value, and the encoding, matching TemplateSegmentConverter's shape.

• Note on 0_converters.ipynb. Regenerating the modality table also picked up two converter rows the
  committed output predated: AcrosticConverter (FEAT: add AcrosticConverter #2280) and VigenereConverter (FEAT: Add VigenereConverter #2333). Nothing was removed.
  Those rows are unrelated to this PR but the table is generated, so trimming them would mean hand-editing
  generated output.

Files

New (10):

• pyrit/converter/code_attack_converter.py
• pyrit/datasets/converters/code_attack_cpp.yaml
• pyrit/datasets/converters/code_attack_go.yaml
• pyrit/datasets/converters/code_attack_python_list.yaml
• pyrit/datasets/converters/code_attack_python_list_plus.yaml
• pyrit/datasets/converters/code_attack_python_stack.yaml
• pyrit/datasets/converters/code_attack_python_stack_plus.yaml
• pyrit/datasets/converters/code_attack_python_string.yaml
• pyrit/datasets/converters/code_attack_python_string_plus.yaml
• tests/unit/converter/test_code_attack_converter.py

Modified (11):

• pyrit/converter/__init__.py
• pyrit/setup/initializers/techniques/core.py
• tests/unit/setup/techniques/test_core_techniques.py
• tests/unit/setup/test_technique_initializer.py
• doc/references.bib
• doc/bibliography.md
• doc/code/converters/0_converters.ipynb
• doc/code/converters/1_text_to_text_converters.py
• doc/code/converters/1_text_to_text_converters.ipynb
• doc/code/executor/1_single_turn.py
• doc/code/executor/1_single_turn.ipynb

Notes

Rebased onto main after the PromptConverter to Converter rename (upstream 3acaaa6), so the converter lives under pyrit/converter/, subclasses Converter, and the seed prompts moved to pyrit/datasets/converters/.

Total diff: 21 files changed, 1450 insertions(+), 68 deletions(-).

Checklist

• pre-commit hooks pass
• Unit tests added and passing locally
• No regressions
• Docstrings on the converter
• Notebook demonstrating usage

[Utkarsh Bahuguna (u7k4rs6)]

PR Risk Summary

Quality Score: 9/10
Risk Level: low
Merge Recommendation: Safe to merge
Rationale: The changes appear to be focused on adding and refining code attack functionalities and their associated prompt converters. The review found no issues, and the changes are well-contained within the relevant modules. The addition of unit tests further strengthens the quality of this pull request.

[Roman Lutz (romanlutz)]

We need a references.bib update to include the paper.

[Utkarsh Bahuguna (u7k4rs6)]

Roman Lutz (@romanlutz) Thanks for the thorough pass. Addressed everything:

Rebased on main; folded the docs into 1_single_turn next to Flip, removed the separate file and myst.yml entry
Added the ren2024codeattack reference and cited it in the docstrings
Renamed CodeAttackAttack to CodeAttack
Collapsed language + verbose into a single enum-typed template param (CodeAttackConverter.Template) that also accepts a custom Path
Kept the attack class but structured it like FlipAttack (system prompt via _setup_async); left the converter independently usable

Open to dropping the class for converter-only if you'd rather. Re-requesting review.

[Utkarsh Bahuguna (u7k4rs6)]

Tracked the framing variant in #2088. Resolving.

[Utkarsh Bahuguna (u7k4rs6)]

Roman Lutz (@romanlutz) Rebased onto current main. The branch was ~150 commits behind, so this
absorbs the PromptConverter → Converter rename from #2161 across all
three directory moves and both symbol renames, and drops the FlipAttack
and ContextComplianceAttack hunks now that those are gone upstream.

Also fixed a gap that predates the rebase: test_all_converters_are_documented
was failing because CodeAttackConverter had no entry under
doc/code/converters/. Added an example to 1_text_to_text_converters,
plus a description= on the code_attack factory so it matches the others.

Converter, docs and setup suites green, pre-commit clean. Description
updated for the new names.

[Utkarsh Bahuguna (u7k4rs6)]

hey Roman Lutz (@romanlutz) , no rush on the review itself, but #1960's CI is stuck awaiting maintainer approval so nothing has actually run on it yet. could you kick that off when you get a sec? also cleaned up the description, the attack class is gone and it's a converter + technique factory now, plus updated the bib entry to the ACL Findings version to match your #2409 pass 🙏

[Roman Lutz (romanlutz)]

This new cell is committed with execution_count: null and no output. The documentation instructions require retaining executed notebook outputs. Please execute and regenerate the paired notebook using this checkout.

[Utkarsh Bahuguna (u7k4rs6)]

This cell runs a live PromptSendingAttack against OpenAIChatTarget and I don't have target credentials, so I can't produce real output for it. I didn't want to fabricate one. Options as I see them: someone with a configured target executes the cell and pushes to the branch (edits by maintainers is on), or the cell becomes an offline convert_async demo, or it ships unexecuted. Any of those works for me, let me know which you prefer. For what it's worth tests/unit/docs passes green as-is and nothing in the hooks or tests inspects execution_count.

[Roman Lutz (romanlutz)]

We'll rerun this notebook before merging, so this is not a problem for the implementation. Leaving the thread open so we don't forget the pre-merge step.

[Utkarsh Bahuguna (u7k4rs6)]

Roman Lutz (@romanlutz) Addressed all of these. The substantive ones: language-aware escaping so non-BMP input survives Go and C++, eager template load with wrapped_input validation, content-hash identifier, and a new Encoding enum so custom Path templates aren't locked to python_string. Tests went 31 to 63 in the converter file plus 2 in core techniques.

One I can't close: the 1_single_turn cell needs a live target and I don't have credentials. Left options on that thread.

Also, CI still hasn't run on this PR at all. All five workflows are stuck awaiting maintainer approval, so none of this has been verified upstream yet. Could you kick that off?

[Roman Lutz (romanlutz)]

Could we reject an encoding that does not match a built-in Template? For example, Template.PYTHON_STACK with Encoding.PYTHON_LIST produces:

my_stack = deque()
my_list.append("alpha")
task = decode(my_stack)

The objective is written to my_list but decoded from the empty my_stack, so the attack silently loses the objective. Custom paths need an explicit encoding, but built-in templates should use their mapped encoding or raise on a mismatch. Am I missing a valid use case for overriding a built-in this way?

[Roman Lutz (romanlutz)]

Could we also reject unsupported template variables during construction? The converter only supplies wrapped_input, so a custom template such as {{ wrapped_input }} {{ suffix }} passes this check and then fails on its first conversion because suffix is undefined. Checking for any remaining undeclared variables here would keep custom-template failures at construction time.