tokenfool 0.0.1__tar.gz

tokenfool-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TrustThink
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tokenfool-0.0.1/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: tokenfool
+Version: 0.0.1
+Author-email: Allison Lane <lane_allison@trustthink.net>
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch
+Requires-Dist: numpy
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: timm; extra == "test"
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: timm; extra == "dev"
+Requires-Dist: torchvision; extra == "dev"
+Requires-Dist: matplotlib; extra == "dev"
+Requires-Dist: tqdm; extra == "dev"
+Requires-Dist: ipywidgets; extra == "dev"
+Dynamic: license-file
+
+# tokenfool
+
+Widely recognized methods for producing adversarial examples (e.g., PGD, FGSM) were developed and popularized in the context of convolutional neural network (CNN)-based image models. These attacks operate in continuous input space and rely on end-to-end differentiability; in practice, they are typically applied as pixel-level perturbations to induce misclassification. Existing open-source adversarial toolkits such as [Foolbox](https://github.com/bethgelab/foolbox), [CleverHans](https://github.com/cleverhans-lab/cleverhans), and [Adversarial Robustness Toolbox (ART)](https://github.com/Trusted-AI/adversarial-robustness-toolbox) consolidate these implementations, enabling users to benchmark robustness and evaluate defenses through standardized interfaces. 
+
+In recent years, transformer-based models have emerged as a dominant alternative to CNNs in computer vision. Architectures such as ViT, DeiT, Swin, and DETR replace convolutional feature extraction with patch tokenization and self-attention mechanisms. These models are now widely deployed across classification, detection, and segmentation tasks. Like CNNs, vision transformers are vulnerable to adversarial examples under standard white-box gradient attacks. However, their token-based representation and global self-attention introduce different structural sensitivities compared to convolutional architectures. In addition to conventional pixel-space perturbations, transformers are susceptible to structured patch-level attacks, token/embedding-space perturbations, and attacks that exploit attention distributions or object query representations in detection models. 
+
+## About
+
+TokenFool is an open-source toolkit for adversarial attacks on image transformers. It is modular and extensible, enabling straightforward integration of new attack algorithms. Attacks operate under gradient-based white-box assumptions and integrate directly with standard PyTorch training and evaluation workflows. Users can support their own models by implementing the interface contract expected by the attacks. This keeps attack code separate from provider-specific or model-specific wiring and makes it possible to extend TokenFool beyond the built-in adapters.
+
+## Current Status
+
+TokenFool currently includes:
+- a core `tokenfool` package for attack implementations
+- an adapter/interface layer for transformer classifier integrations
+- example usage notebooks 
+- automated test coverage
+- repository CI workflows
+
+Current attack coverage includes:
+- **Patch-Fool** ([paper](https://arxiv.org/abs/2203.08392))
+- **Adaptive Token Tuning (ATT)** ([paper](https://proceedings.neurips.cc/paper_files/paper/2024/hash/24f8dd1b8f154f1ee0d7a59e368eccf3-Abstract-Conference.html))
+
+Current model support is focused on:
+- **timm-style ViT/DeiT classifier implementations**
+- **user-defined models that implement the required interface contract via a custom adapter**
+
+## Next Steps
+
+Planned expansion areas include:
+- additional transformer-specific attack methods
+- broader model-family and provider coverage
+- support for non-classification transformer settings through new interfaces and adapters
+
+
+## TokenFool Architecture
+
+![Architecture diagram](architecture.png)
+
+The library is structured as a layered system: attacks depend on stable interface contracts rather than directly on model implementations. Concrete adapters bridge those interfaces to supported model implementations, while custom adapters provide the path for integrating user-owned models without changing attack logic.
+
+## Development
+
+1. Clone the repository   
+(**External contributors**: fork the repository first, then clone your fork)
+```bash
+git clone https://github.com/TrustThink/tokenfool.git
+cd tokenfool
+```
+2. (Recommended) Create a virtual environment
+
+3. Install the project in editable mode with development dependencies
+```bash
+pip install -e ".[dev]"
+```
+
+4. Make changes on a new branch, including tests were appropriate
+
+5. Run tests
+```bash
+pytest
+```
+
+6. Run lint checks
+```bash
+ruff check
+```
+
+7. Open a Pull Request
+
+Repository checks also run through GitHub Actions.

tokenfool-0.0.1/README.md

@@ -0,0 +1,71 @@
+# tokenfool
+
+Widely recognized methods for producing adversarial examples (e.g., PGD, FGSM) were developed and popularized in the context of convolutional neural network (CNN)-based image models. These attacks operate in continuous input space and rely on end-to-end differentiability; in practice, they are typically applied as pixel-level perturbations to induce misclassification. Existing open-source adversarial toolkits such as [Foolbox](https://github.com/bethgelab/foolbox), [CleverHans](https://github.com/cleverhans-lab/cleverhans), and [Adversarial Robustness Toolbox (ART)](https://github.com/Trusted-AI/adversarial-robustness-toolbox) consolidate these implementations, enabling users to benchmark robustness and evaluate defenses through standardized interfaces. 
+
+In recent years, transformer-based models have emerged as a dominant alternative to CNNs in computer vision. Architectures such as ViT, DeiT, Swin, and DETR replace convolutional feature extraction with patch tokenization and self-attention mechanisms. These models are now widely deployed across classification, detection, and segmentation tasks. Like CNNs, vision transformers are vulnerable to adversarial examples under standard white-box gradient attacks. However, their token-based representation and global self-attention introduce different structural sensitivities compared to convolutional architectures. In addition to conventional pixel-space perturbations, transformers are susceptible to structured patch-level attacks, token/embedding-space perturbations, and attacks that exploit attention distributions or object query representations in detection models. 
+
+## About
+
+TokenFool is an open-source toolkit for adversarial attacks on image transformers. It is modular and extensible, enabling straightforward integration of new attack algorithms. Attacks operate under gradient-based white-box assumptions and integrate directly with standard PyTorch training and evaluation workflows. Users can support their own models by implementing the interface contract expected by the attacks. This keeps attack code separate from provider-specific or model-specific wiring and makes it possible to extend TokenFool beyond the built-in adapters.
+
+## Current Status
+
+TokenFool currently includes:
+- a core `tokenfool` package for attack implementations
+- an adapter/interface layer for transformer classifier integrations
+- example usage notebooks 
+- automated test coverage
+- repository CI workflows
+
+Current attack coverage includes:
+- **Patch-Fool** ([paper](https://arxiv.org/abs/2203.08392))
+- **Adaptive Token Tuning (ATT)** ([paper](https://proceedings.neurips.cc/paper_files/paper/2024/hash/24f8dd1b8f154f1ee0d7a59e368eccf3-Abstract-Conference.html))
+
+Current model support is focused on:
+- **timm-style ViT/DeiT classifier implementations**
+- **user-defined models that implement the required interface contract via a custom adapter**
+
+## Next Steps
+
+Planned expansion areas include:
+- additional transformer-specific attack methods
+- broader model-family and provider coverage
+- support for non-classification transformer settings through new interfaces and adapters
+
+
+## TokenFool Architecture
+
+![Architecture diagram](architecture.png)
+
+The library is structured as a layered system: attacks depend on stable interface contracts rather than directly on model implementations. Concrete adapters bridge those interfaces to supported model implementations, while custom adapters provide the path for integrating user-owned models without changing attack logic.
+
+## Development
+
+1. Clone the repository   
+(**External contributors**: fork the repository first, then clone your fork)
+```bash
+git clone https://github.com/TrustThink/tokenfool.git
+cd tokenfool
+```
+2. (Recommended) Create a virtual environment
+
+3. Install the project in editable mode with development dependencies
+```bash
+pip install -e ".[dev]"
+```
+
+4. Make changes on a new branch, including tests were appropriate
+
+5. Run tests
+```bash
+pytest
+```
+
+6. Run lint checks
+```bash
+ruff check
+```
+
+7. Open a Pull Request
+
+Repository checks also run through GitHub Actions.

tokenfool-0.0.1/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tokenfool"
+version = "0.0.1"
+authors = [
+  { name="Allison Lane", email="lane_allison@trustthink.net"}
+]
+readme = "README.md"
+requires-python = ">=3.10"
+license="MIT"
+license-files = ["LICENSE"]
+dependencies = [
+  "torch",
+  "numpy",
+]
+
+[project.optional-dependencies]
+test = [
+  "pytest",
+  "timm",
+]
+
+dev = [
+  "ruff",
+  "mypy",
+  "pytest",
+  "timm",
+  "torchvision",
+  "matplotlib",
+  "tqdm",
+  "ipywidgets",
+]
+
+[tool.mypy]
+python_version = "3.11"
+ignore_missing_imports = true
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["tokenfool*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

tokenfool-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tokenfool-0.0.1/tests/test_att.py

@@ -0,0 +1,237 @@
+import torch
+import torch.nn as nn
+import pytest
+
+from tokenfool.attacks.att import ATT
+
+MEAN = (0.485, 0.456, 0.406)
+STD = (0.229, 0.224, 0.225)
+
+class MockAttn(nn.Module):
+    def __init__(self, dim: int):
+        super().__init__()
+        self.qkv = nn.Linear(dim, dim)
+        self.attn_drop = nn.Identity()
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return self.attn_drop(self.qkv(x))
+
+
+class MockBlock(nn.Module):
+    def __init__(self, dim: int):
+        super().__init__()
+        self.attn = MockAttn(dim)
+        self.mlp = nn.Linear(dim, dim)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        x = x + self.attn(x)
+        x = x + self.mlp(x)
+        return x
+
+
+class TinyBackbone(nn.Module):
+    def __init__(self, image_size=32, patch_size=8, dim=8, num_classes=5, num_prefix_tokens=1):
+        super().__init__()
+        assert image_size % patch_size == 0
+        patch_dim = 3 * patch_size * patch_size
+
+        self.num_prefix_tokens = num_prefix_tokens
+        self.patch_size = patch_size
+        self.patch_proj = nn.Linear(patch_dim, dim)
+        self.prefix = nn.Parameter(torch.zeros(1, num_prefix_tokens, dim))
+        self.blocks = nn.ModuleList([MockBlock(dim), MockBlock(dim)])
+        self.head = nn.Linear(dim, num_classes)
+
+    def _to_tokens(self, x: torch.Tensor) -> torch.Tensor:
+        B, C, H, W = x.shape
+        p = self.patch_size
+        g = H // p
+        patches = x.unfold(2, p, p).unfold(3, p, p)
+        patches = patches.permute(0, 2, 3, 1, 4, 5).reshape(B, g * g, C * p * p)
+        patch_tokens = self.patch_proj(patches)
+        prefix = self.prefix.expand(B, -1, -1)
+        return torch.cat([prefix, patch_tokens], dim=1)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        x = self._to_tokens(x)
+        for blk in self.blocks:
+            x = blk(x)
+        return self.head(x[:, 0])
+
+
+class DummyHookableViT:
+    def __init__(self, backbone: TinyBackbone):
+        self.model = backbone
+
+    @property
+    def num_prefix_tokens(self) -> int:
+        return self.model.num_prefix_tokens
+
+    def zero_grad(self, set_to_none: bool = True) -> None:
+        self.model.zero_grad(set_to_none=set_to_none)
+
+    def logits(self, x: torch.Tensor) -> torch.Tensor:
+        return self.model(x)
+
+    def hook_modules(self):
+        return {
+            "attn_drop": [blk.attn.attn_drop for blk in self.model.blocks],
+            "qkv": [blk.attn.qkv for blk in self.model.blocks],
+            "mlp": [blk.mlp for blk in self.model.blocks],
+        }
+
+    def att_feature_module(self):
+        return self.model.blocks[-2]
+    
+
+
+@pytest.mark.parametrize("patch_out", [False, True])
+@pytest.mark.parametrize("num_prefix_tokens", [1, 2])
+def test_att_shapes_and_bounds(patch_out, num_prefix_tokens):
+    torch.manual_seed(0)
+    device = torch.device("cpu")
+
+    B, C, H, W = 2, 3, 32, 32
+    x = torch.rand(B, C, H, W, device=device)
+
+    backbone = TinyBackbone(
+        image_size=H,
+        patch_size=8,
+        dim=32,
+        num_classes=7,
+        num_prefix_tokens=num_prefix_tokens,
+    ).to(device)
+    model = DummyHookableViT(backbone)
+
+    x_adv = ATT(
+        model,
+        x,
+        y=None,
+        epsilon=8 / 255,
+        iters=3,
+        decay=1.0,
+        patch_out=patch_out,
+        patch_size=8,
+        image_size=H,
+        progress=False,
+    )
+
+    assert x_adv.shape == x.shape
+    assert torch.isfinite(x_adv).all()
+
+    mu_t = torch.tensor(MEAN, device=device, dtype=x.dtype).view(1, 3, 1, 1)
+    std_t = torch.tensor(STD, device=device, dtype=x.dtype).view(1, 3, 1, 1)
+    lo = (0 - mu_t) / std_t
+    hi = (1 - mu_t) / std_t
+
+    assert torch.all(x_adv >= lo - 1e-6)
+    assert torch.all(x_adv <= hi + 1e-6)
+
+
+def test_att_changes_input():
+    torch.manual_seed(0)
+    device = torch.device("cpu")
+
+    x = torch.rand(1, 3, 32, 32, device=device)
+
+    backbone = TinyBackbone(
+        image_size=32,
+        patch_size=8,
+        dim=32,
+        num_classes=5,
+        num_prefix_tokens=1,
+    ).to(device)
+    model = DummyHookableViT(backbone)
+
+    x_adv = ATT(
+        model,
+        x,
+        epsilon=8 / 255,
+        iters=3,
+        patch_out=True,
+        patch_size=8,
+        image_size=32,
+        progress=False,
+    )
+
+    diff = (x_adv - x).abs().max().item()
+    assert diff > 0.0
+
+
+def test_att_targeted_smoke():
+    torch.manual_seed(0)
+    device = torch.device("cpu")
+
+    x = torch.rand(2, 3, 32, 32, device=device)
+    target = torch.tensor([1, 2], device=device)
+
+    backbone = TinyBackbone(
+        image_size=32,
+        patch_size=8,
+        dim=32,
+        num_classes=5,
+        num_prefix_tokens=1,
+    ).to(device)
+    model = DummyHookableViT(backbone)
+
+    x_adv = ATT(
+        model,
+        x,
+        y=target,
+        epsilon=8 / 255,
+        iters=2,
+        targeted=True,
+        patch_out=True,
+        patch_size=8,
+        image_size=32,
+        progress=False,
+    )
+
+    assert x_adv.shape == x.shape
+    assert torch.isfinite(x_adv).all()
+
+
+def test_att_respects_pixel_epsilon_in_unnormalized_space():
+    torch.manual_seed(0)
+    device = torch.device("cpu")
+
+    x = torch.rand(1, 3, 32, 32, device=device)
+
+    backbone = TinyBackbone(
+        image_size=32,
+        patch_size=8,
+        dim=32,
+        num_classes=5,
+        num_prefix_tokens=1,
+    ).to(device)
+    model = DummyHookableViT(backbone)
+
+    x_adv = ATT(
+        model,
+        x,
+        epsilon=8 / 255,
+        iters=3,
+        patch_out=True,
+        patch_size=8,
+        image_size=32,
+        progress=False,
+    )
+
+    mu_t = torch.tensor(MEAN, device=device, dtype=x.dtype).view(1, 3, 1, 1)
+    std_t = torch.tensor(STD, device=device, dtype=x.dtype).view(1, 3, 1, 1)
+    x_pix = (x * std_t + mu_t).clamp(0, 1)
+    x_adv_pix = (x_adv * std_t + mu_t).clamp(0, 1)
+
+    diff = (x_adv_pix - x_pix).abs()
+    assert torch.all(diff <= 8 / 255 + 1e-5)
+
+
+def test_att_missing_hook_methods_raises():
+    class BadModel:
+        def logits(self, x):
+            return x.mean(dim=(2, 3))
+
+    x = torch.rand(1, 3, 32, 32)
+
+    with pytest.raises(TypeError):
+        ATT(BadModel(), x, iters=1, progress=False)

tokenfool-0.0.1/tests/test_patchfool.py

@@ -0,0 +1,174 @@
+import torch
+import torch.nn as nn
+import pytest
+
+from tokenfool.attacks.patchfool import PatchFool, _infer_special_tokens_from_attn
+
+class DummyViT(nn.Module):
+    """
+    Minimal differentiable model TransformerClassifier for tests
+    """
+    def __init__(self, num_classes=10, heads=2, grid=4, specials=1, layers=6):
+        super().__init__()
+        self.num_classes = num_classes
+        self.heads = heads
+        self.grid = grid
+        self.specials = specials
+        self.N = specials + grid * grid
+        self.layers = layers
+        self.proj = nn.Linear(3, num_classes)
+
+
+    def logits(self, x: torch.Tensor) -> torch.Tensor:
+        feat = x.mean(dim=(2, 3))
+        return self.proj(feat)
+
+    def logits_and_attn(self, x: torch.Tensor):
+        logits = self.logits(x)
+        B = x.size(0)
+        device = x.device
+        base = x.mean(dim=(2, 3), keepdim=False)  
+        s = base.sum(dim=1, keepdim=True)         
+        A = torch.sigmoid(s).view(B, 1, 1, 1) * torch.ones(B, self.heads, self.N, self.N, device=device)
+        A = A / (A.sum(dim=-1, keepdim=True) + 1e-12)  
+
+        attn_list = [A for _ in range(self.layers)]
+        return logits, attn_list
+
+
+def normalized_bounds(mu, std, device):
+    mu_t = torch.tensor(mu, device=device).view(1, 3, 1, 1)
+    std_t = torch.tensor(std, device=device).view(1, 3, 1, 1)
+    lo = (0 - mu_t) / std_t
+    hi = (1 - mu_t) / std_t
+    return lo, hi, std_t
+
+
+def test_infer_special_tokens_basic():
+    assert _infer_special_tokens_from_attn(197) == 1
+    assert _infer_special_tokens_from_attn(198) == 2
+
+
+@pytest.mark.parametrize("patch_select", ["Rand", "Saliency", "Attn"])
+def test_patchfool_shapes_and_bounds(patch_select):
+    torch.manual_seed(0)
+    device = torch.device("cpu")
+
+    B, C, H, W = 2, 3, 64, 64
+    x = torch.rand(B, C, H, W, device=device)
+    model = DummyViT(grid=H // 16, specials=1).to(device)
+
+    x_adv, mask = PatchFool(
+        model,
+        x,
+        y=None,
+        patch_size=16,
+        num_patch=1,
+        sparse_pixel_num=0,
+        patch_select=patch_select,
+        attack_mode="CE_loss",
+        iters=3,          # fast
+        lr=0.1,
+        mild_l_inf=0.0,
+        mild_l_2=0.0,
+        device=device,
+    )
+
+    assert x_adv.shape == x.shape
+    assert mask.shape == (B, 1, H, W)
+
+    # bounds check
+    lo, hi, _ = normalized_bounds((0.485,0.456,0.406), (0.229,0.224,0.225), device)
+    assert torch.all(x_adv >= lo - 1e-6)
+    assert torch.all(x_adv <= hi + 1e-6)
+
+
+def test_patchfool_mask_locality_sparse0():
+    torch.manual_seed(0)
+    device = torch.device("cpu")
+
+    B, C, H, W = 1, 3, 64, 64
+    x = torch.rand(B, C, H, W, device=device)
+    model = DummyViT(grid=H // 16, specials=1).to(device)
+
+    x_adv, mask = PatchFool(
+        model,
+        x,
+        y=None,
+        patch_size=16,
+        num_patch=1,
+        sparse_pixel_num=0,
+        patch_select="Rand",
+        attack_mode="CE_loss",
+        iters=3,
+        lr=0.1,
+        device=device,
+    )
+
+    diff = (x_adv - x).abs()
+    outside = diff * (1 - mask)
+    assert outside.max().item() <= 1e-5
+
+
+def test_patchfool_linf_constraint():
+    torch.manual_seed(0)
+    device = torch.device("cpu")
+
+    B, C, H, W = 1, 3, 64, 64
+    x = torch.rand(B, C, H, W, device=device)
+    model = DummyViT(grid=H // 16, specials=1).to(device)
+
+    mild_l_inf = 0.05
+    x_adv, mask = PatchFool(
+        model,
+        x,
+        y=None,
+        patch_size=16,
+        num_patch=1,
+        sparse_pixel_num=0,
+        patch_select="Rand",
+        attack_mode="CE_loss",
+        iters=5,
+        lr=0.2,
+        mild_l_inf=mild_l_inf,
+        mild_l_2=0.0,
+        device=device,
+    )
+
+    _, _, std_t = normalized_bounds((0.485,0.456,0.406), (0.229,0.224,0.225), device)
+    eps = mild_l_inf / std_t
+    diff = (x_adv - x).abs()
+    assert torch.all(diff <= eps + 1e-5)
+
+
+def test_patchfool_l2_constraint():
+    torch.manual_seed(0)
+    device = torch.device("cpu")
+
+    B, C, H, W = 1, 3, 64, 64
+    x = torch.rand(B, C, H, W, device=device)
+    model = DummyViT(grid=H // 16, specials=1).to(device)
+
+    mild_l_2 = 1.0
+    x_adv, mask = PatchFool(
+        model,
+        x,
+        y=None,
+        patch_size=16,
+        num_patch=1,
+        sparse_pixel_num=0,
+        patch_select="Rand",
+        attack_mode="CE_loss",
+        iters=5,
+        lr=0.2,
+        mild_l_inf=0.0,
+        mild_l_2=mild_l_2,
+        device=device,
+    )
+
+    _, _, std_t = normalized_bounds((0.485,0.456,0.406), (0.229,0.224,0.225), device)
+    radius = (mild_l_2 / std_t).view(1, C)  
+
+    pert = (x_adv - x) * mask
+    l2 = torch.linalg.norm(pert.view(B, C, -1), dim=-1)  
+    assert torch.all(l2 <= radius + 1e-4)