cobra-mba

Python bindings for CoBRA, a Rust simplifier for mixed Boolean-arithmetic (MBA) expressions.

import cobra_mba

result = cobra_mba.simplify("(x ^ y) + 2 * (x & y)")
print(result)                 # x + y
print(result.proof_level)     # ProofLevel.LEAN_CERTIFIED

Wheels carry the compiled simplifier, so there is nothing else to install. The package name is cobra-mba because cobra on PyPI belongs to an unrelated project; the import name is cobra_mba.

Install

pip install cobra-mba

Wheels are published for CPython 3.10 and newer on Linux (x86-64 and aarch64), macOS, and Windows x64. Any other platform builds from the source distribution and needs a Rust toolchain.

Expressions

Expr pairs an expression tree with the variable names its indices refer to, so trees built separately can still be combined.

from cobra_mba import Expr

e = Expr.parse("(x ^ y) + 2 * (x & y)")
e.variables            # ['x', 'y']
e.evaluate(x=3, y=5)   # 8
e.kind                 # Kind.ADD
str(e.children[0])     # 'x ^ y'

Operators build the same trees the parser does:

x, y = Expr.var("x"), Expr.var("y")
(x ^ y) + 2 * (x & y) == Expr.parse("(x ^ y) + 2 * (x & y)")   # True

Variables are sorted lexicographically, matching the parser, so Expr.var("b") + Expr.var("a") renders with a first.

Expressions are immutable, hashable, comparable, and picklable. to_dict and Expr.from_dict give a plain-data form suitable for JSON.

Results

simplify returns the whole outcome rather than just an expression:

result = cobra_mba.simplify("x * x * x", bitwidth=32)
result.kind            # OutcomeKind.UNCHANGED_UNSUPPORTED
result.diagnostic.reason
result.telemetry.total_expansions

A pipeline error is a value, not an exception, so its diagnostic can be inspected. Call result.raise_for_error() when an exception is the more convenient shape. Bad input still raises: ParseError, InvalidArgumentError, and TooManyVariablesError all subclass both CobraError and ValueError.

Certificates and soundness

By default a simplification is discarded unless a replayable Lean certificate covers its exact output. This is the soundness gate: full-width checking is finite probing, and a candidate can differ from the original at one point no probe reaches.

cobra_mba.simplify(expr_text, require_lean_certificate=False)

Turning the gate off accepts probe-only assurance. It raises the simplification rate a great deal and is reasonable when inputs are not adversarial.

Doing a lot at once

simplify_many hands the whole batch over in one call and spreads it across every core with the interpreter lock released:

from cobra_mba import simplify_many

results = simplify_many(expressions, require_lean_certificate=False)

Results come back in input order. Pass on_error="none" to get None in place of an item that failed to parse, so one bad line does not cost the batch, and workers= to fix the thread count. Measured on six cores, it runs about four times faster than calling simplify in a loop.

evaluate_many evaluates one expression at many points in a single call:

expr = Expr.parse("(x ^ y) + 2 * (x & y)")
expr.evaluate_many({"x": [1, 2, 3], "y": [10, 20, 30]})

Columns may be sequences of integers, or bytes holding one little-endian 64-bit value per point. The bytes form is the fast one, and raw=True returns results in the same shape, which is what NumPy reads and writes directly:

import numpy as np

xs = np.array(..., dtype=np.uint64)
ys = np.array(..., dtype=np.uint64)
raw = expr.evaluate_many({"x": xs.tobytes(), "y": ys.tobytes()}, raw=True)
out = np.frombuffer(raw, dtype="<u8")

Measured on 50 000 points, against a Python loop over evaluate:

How the points are passed Relative speed
One point at a time 1.0x
Lists 7.0x
Bytes in 16.4x
Bytes in and out 25.4x

There is no zero-copy buffer path. Python only added the buffer protocol to its stable ABI in 3.11, and these wheels target 3.10, so bytes are as close as the stable ABI gets. See examples/ for both in use.

Threads

Every call releases the interpreter lock and runs the pipeline on a worker thread with a large stack, so a thread pool scales and deeply nested expressions do not overflow Python's own stack.

from concurrent.futures import ThreadPoolExecutor

with ThreadPoolExecutor(8) as pool:
    results = list(pool.map(cobra_mba.simplify, expressions))

Limits

Limit Value
Bit width 1 to 64
Variables 20
Input size 1 MiB, 100 000 tokens
Parsed depth 512

Mixed-width trees, built with zext, sext, trunc, and concat, are supported by the expression layer. The text parser cannot express casts, and constants take the expression's global bit width rather than a local one, so a mixed-width tree that also mixes constant widths will not validate.

License

Apache-2.0. CoBRA was originally developed by Kyle Elliott and Trail of Bits.

Project links

Data verified by PyPI on Sep 2, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for thehorse from gravatar.com thehorse

Credits

Author: The CoBRA contributors

GitHub Statistics

Data verified by PyPI on Sep 2, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.10

Tags

bitvector mba simplifier deobfuscation reverse-engineering

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cobra_mba-0.4.0.tar.gz (739.4 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

cobra_mba-0.4.0-cp310-abi3-win_amd64.whl (1.1 MB view details)

Uploaded CPython 3.10+Windows x86-64

cobra_mba-0.4.0-cp310-abi3-manylinux_2_28_x86_64.whl (1.3 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.28+ x86-64

cobra_mba-0.4.0-cp310-abi3-manylinux_2_28_aarch64.whl (1.2 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.28+ ARM64

cobra_mba-0.4.0-cp310-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl (2.3 MB view details)

Uploaded CPython 3.10+macOS 10.12+ universal2 (ARM64, x86-64)macOS 10.12+ x86-64macOS 11.0+ ARM64

File details

Details for the file cobra_mba-0.4.0.tar.gz.

File metadata

  • Download URL: cobra_mba-0.4.0.tar.gz
  • Upload date:
  • Size: 739.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for cobra_mba-0.4.0.tar.gz
Algorithm Hash digest
SHA256 35d6cf41fd40ea0aa3bfa31fe04ff55ee7ea59c782825d0667287f150e489592
MD5 44db0f30c019442007e3457914ea422c
BLAKE2b-256 427833470c82ecee988e1ff3e34d508a3284d5b11f2af8b4da0e28844248d686

See more details on using hashes here.

Provenance

The following attestation bundles were made for cobra_mba-0.4.0.tar.gz:

Publisher: release.yml on binsnake/cobra

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file cobra_mba-0.4.0-cp310-abi3-win_amd64.whl.

File metadata

  • Download URL: cobra_mba-0.4.0-cp310-abi3-win_amd64.whl
  • Upload date:
  • Size: 1.1 MB
  • Tags: CPython 3.10+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for cobra_mba-0.4.0-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 a0707865e077c84ce9ae427cd89004dc84b14e8cd6f8c5725c9318dbe81ac12d
MD5 9ca17034e0c5de55ab10394d182216a4
BLAKE2b-256 b956359cc423ee75bda1cf2b753eedf7b89f97902f843a66d9d805b01295cd71

See more details on using hashes here.

Provenance

The following attestation bundles were made for cobra_mba-0.4.0-cp310-abi3-win_amd64.whl:

Publisher: release.yml on binsnake/cobra

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file cobra_mba-0.4.0-cp310-abi3-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for cobra_mba-0.4.0-cp310-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 9d4d019cb42f19edea31da09384c9c36b500d0c20b31fc77a02250643fa75238
MD5 bea55ec2ed0b46fb3235246937e2d938
BLAKE2b-256 017e30c33f16ba37cb64e493d3762cf7e6007ab39457ef498bfa217421acddc3

See more details on using hashes here.

Provenance

The following attestation bundles were made for cobra_mba-0.4.0-cp310-abi3-manylinux_2_28_x86_64.whl:

Publisher: release.yml on binsnake/cobra

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file cobra_mba-0.4.0-cp310-abi3-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for cobra_mba-0.4.0-cp310-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 d7e693395bf5ecdb8f6a8e98918358fe0048d75940dd4be0bc7721352b59cf35
MD5 6528d05b5871782b6908e1141c399d7d
BLAKE2b-256 0b447a4ee816d1337b8a7996d33de572c03a5dc9162753cdc3cf9d70ca133fd3

See more details on using hashes here.

Provenance

The following attestation bundles were made for cobra_mba-0.4.0-cp310-abi3-manylinux_2_28_aarch64.whl:

Publisher: release.yml on binsnake/cobra

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file cobra_mba-0.4.0-cp310-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl.

File metadata

File hashes

Hashes for cobra_mba-0.4.0-cp310-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
Algorithm Hash digest
SHA256 de6fd1272eef997d90e7dfc4422a26eac87920ade7d703091b9bf3f430432cda
MD5 16a15e91c6924de63280d670defed2a7
BLAKE2b-256 f54b067707a754391e1b1960852165d3afd4806fa1e8b446e115e19578986a8a

See more details on using hashes here.

Provenance

The following attestation bundles were made for cobra_mba-0.4.0-cp310-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl:

Publisher: release.yml on binsnake/cobra

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.4.0 This release

5 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page