{"id":26281915,"url":"https://github.com/aviggiano/circom-mutator","last_synced_at":"2026-01-02T12:20:41.044Z","repository":{"id":176502845,"uuid":"658807773","full_name":"aviggiano/circom-mutator","owner":"aviggiano","description":"Mutation testing tool for circom","archived":false,"fork":false,"pushed_at":"2023-07-04T17:44:53.000Z","size":110,"stargazers_count":16,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-05T12:19:17.528Z","etag":null,"topics":["circom","mutation","mutator","zero-knowledge"],"latest_commit_sha":null,"homepage":"","language":"Circom","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aviggiano.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-26T14:27:53.000Z","updated_at":"2024-10-21T21:06:00.000Z","dependencies_parsed_at":null,"dependency_job_id":"16302aca-b63c-4377-8edd-e55cb19c3c94","html_url":"https://github.com/aviggiano/circom-mutator","commit_stats":{"total_commits":38,"total_committers":1,"mean_commits":38.0,"dds":0.0,"last_synced_commit":"e915f8d819b814541155f1a35a9f53702e41fc9c"},"previous_names":["aviggiano/circom-mutator"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aviggiano%2Fcircom-mutator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aviggiano%2Fcircom-mutator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aviggiano%2Fcircom-mutator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aviggiano%2Fcircom-mutator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aviggiano","download_url":"https://codeload.github.com/aviggiano/circom-mutator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243606959,"owners_count":20318314,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["circom","mutation","mutator","zero-knowledge"],"created_at":"2025-03-14T16:17:22.627Z","updated_at":"2026-01-02T12:20:40.983Z","avatar_url":"https://github.com/aviggiano.png","language":"Circom","funding_links":[],"categories":[],"sub_categories":[],"readme":"# circom-mutator\n\nMutation testing tool for circom\n\n# How it works\n\n`circom-mutator` is a mutation testing tool designed for the circom programming language. This tool primarily revolves around the source-based rewrite of circom code lines to generate mutations.\n\n\nCurrently, it operates by utilizing regular expressions to treat the code as text. This methodology may evolve in the future, potentially incorporating the transpiling of circom circuits into an intermediate representation to enable deeper analyses.\n\nThe majority of mutators present in `circom-mutator` are based on:\n\n- [0xPARC's ZK Bug Tracker](https://github.com/0xPARC/zk-bug-tracker#dark-forest-1)\n- [Circomspect's analysis passes](https://github.com/trailofbits/circomspect/blob/main/doc/analysis_passes.md)\n- [yAcademy ZK Fellowship audits](https://github.com/zBlock-1)\n\n\nContributions are welcomed. If you wish to include a new test case or if you've identified any bugs in the wild using this tool, feel free to submit a pull request.\n\n# Usage\n\nYou can either use `circom-mutator` as a standalone CLI or integrate it into your project and leverage its API in your tests. \n\n## CLI\n\n```\nnpx circom-mutator \u003cfiles\u003e [--out-dir \u003cdirectory\u003e]\n```\n\nThis will generate all possible mutants from the provided input file.\n\n## Test integration\n\nInstall the package using npm or yarn:\n\n```\nnpm install --dev circom-mutator\n# or\nyarn add -D circom-mutator\n```\n\nOnce you have installed circom-mutator in your project, you can use the `testMutations` in your test files:\n\n```typescript\ntestMutations({\n  description: \"eff_ecdsa\",\n  filename: path.join(__dirname, \"./circuits/eff_ecdsa_test.circom\"),\n  test: async () =\u003e {\n    const circuit = await wasm_tester(\n      path.join(__dirname, \"./circuits/eff_ecdsa_test.circom\"),\n      {\n        prime: \"secq256k1\"\n      }\n    );\n\n    const privKey = Buffer.from(\n      \"f5b552f608f5b552f608f5b552f6082ff5b552f608f5b552f608f5b552f6082f\",\n      \"hex\"\n    );\n    const pubKey = ec.keyFromPrivate(privKey.toString(\"hex\")).getPublic();\n    const msg = Buffer.from(\"hello world\");\n    const circuitInput = getEffEcdsaCircuitInput(privKey, msg);\n\n    const w = await circuit.calculateWitness(circuitInput, true);\n\n    await circuit.assertOut(w, {\n      pubKeyX: pubKey.x.toString(),\n      pubKeyY: pubKey.y.toString()\n    });\n\n    // mutated circuits should make tests fail\n    expect(async () =\u003e await circuit.checkConstraints(w)).toThrow();\n  }\n});\n```\n\nThis will output the diff between the mutants and the original circuit as well as the test results. A fail means the mutated circuit was still able to pass the test, which is not desireable.\n\n# False positives\n\nPlease note that this tool may generate numerous false positives. Not all circuits will check for every possible constraint, as some are expected to be implemented at the application layer.\n\nFor instance, certain circuits may permit an attacker to create fake witnesses by randomly selecting edge cases (such as zero point, points at infinity, or additions with p \u0026 -p). These circuits will expect app developers to perform these verifications.\n\nNevertheless, it remains important to verify that failures detected by `circom-mutator` are indeed false positives, rather than a result of insufficient test coverage.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faviggiano%2Fcircom-mutator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faviggiano%2Fcircom-mutator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faviggiano%2Fcircom-mutator/lists"}