{"_id":"@carmineh/sumo","name":"@carmineh/sumo","dist-tags":{"latest":"3.0.78"},"versions":{"3.0.78":{"author":{"name":"Anonymus"},"name":"@carmineh/sumo","version":"3.0.78","description":"A mutation testing tool for Ethereum smart contracts","repository":{"type":"git","url":"git+https://github.com/GerardoIuliano/MuSe.git"},"publishConfig":{"access":"public"},"main":"index.js","bin":{"sumo":"index.js"},"keywords":["mutation testing","solidity","smart contract"],"scripts":{"postinstall":"node ./scripts/init.js","compile":"npx hardhat compile","test":"hardhat test --bail && forge test --fail-fast"},"dependencies":{"@geriul/sumo":"^3.0.78","@solidity-parser/parser":"^0.15.0","app-root-path":"3.1.0","chalk":"^4.1.2","diff":"^5.0.0","excel4node":"^1.7.2","express":"^4.21.2","fast-csv":"4.3.6","fs-extra":"^10.1.0","glob":"8.1.0","papaparse":"5.4.1","postinstall":"^0.8.0","recursive-copy":"^2.0.14","sha1":"^1.1.1","yargs":"^17.5.1"},"devDependencies":{"hardhat":"^2.26.1"},"_id":"@carmineh/sumo@3.0.78","gitHead":"094dcf3859e48878b1c08d3589060b2cdf94cbf7","bugs":{"url":"https://github.com/GerardoIuliano/MuSe/issues"},"homepage":"https://github.com/GerardoIuliano/MuSe#readme","_nodeVersion":"22.17.1","_npmVersion":"10.8.1","dist":{"integrity":"sha512-gfjF446kateeGrdhjrEoEUQWruAkD2qa2CktvSmC+fIFPygM3CjZb4Kn7R2Ly1DNiy/A0aZY99HigY3RGmIIQQ==","shasum":"c7d8ee39691ba952cb88bad0da333dd2896115d5","tarball":"https://registry.npmjs.org/@carmineh/sumo/-/sumo-3.0.78.tgz","fileCount":103,"unpackedSize":878701,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDQogGWe5ybH5yg/42W2Jrnmw8Cr0BXl/U7s+pS1dB7FQIhAJUcIlCo9uNOcJMatJZOfigWHwjTaiByXJMXdpcbuyEW"}]},"_npmUser":{"name":"carmineh","email":"carmine.calabrese99@gmail.com"},"directories":{},"maintainers":[{"name":"carmineh","email":"carmine.calabrese99@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sumo_3.0.78_1753794570888_0.5199174474202903"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-29T13:09:30.768Z","3.0.78":"2025-07-29T13:09:31.128Z","modified":"2025-07-29T13:09:31.444Z"},"maintainers":[{"name":"carmineh","email":"carmine.calabrese99@gmail.com"}],"description":"A mutation testing tool for Ethereum smart contracts","homepage":"https://github.com/GerardoIuliano/MuSe#readme","keywords":["mutation testing","solidity","smart contract"],"repository":{"type":"git","url":"git+https://github.com/GerardoIuliano/MuSe.git"},"author":{"name":"Anonymus"},"bugs":{"url":"https://github.com/GerardoIuliano/MuSe/issues"},"readme":"<div style=\"text-align:center\">\r\n<img src=\"/logo.png\" alt=\"MuSe logo\" style=\"width:25%;\"/>\r\n</div>\r\n\r\n# MuSe - MUtation SEeding tool\r\nA mutation-based tool for generating benchmarks by injecting vulnerabilities into smart contracts. It features 6 mutation operators to inject vulnerabilities.\r\nMuSe is based on a mutation testing tool called [SuMo](https://github.com/MorenaBarboni/SuMo-SOlidity-MUtator).\r\n\r\n\r\n# Table of Contents\r\n* [Installation](https://github.com/GerardoIuliano/SuMo-SOlidity-MUtator#installation)\r\n* [Configuration](https://github.com/GerardoIuliano/SuMo-SOlidity-MUtator#configuration-)\r\n* [CLI Usage](https://github.com/GerardoIuliano/SuMo-SOlidity-MUtator#cli-usage)\r\n* [Mutation Operators](https://github.com/GerardoIuliano/SuMo-SOlidity-MUtator#mutation-operators-)\r\n* [Publications](https://github.com/GerardoIuliano/SuMo-SOlidity-MUtator#publications)\r\n\r\n\r\n\r\n# Installation 🔌\r\n\r\nTo install sumo run ```npm install @geriul/sumo```\r\n\r\n# Configuration ⚙️\r\nBefore using MuSe you must specify your desired configuration in a [sumo-config.js](https://github.com/GerardoIuliano/SuMo-SOlidity-MUtator/blob/master/src/sumo-config.js) in the root directory of your project. The ```sumo-config.js``` is automatically generated upon installation.\r\n\r\nHere's a simple example of ```sumo-config.js```:\r\n\r\n```\r\nmodule.exports = {\r\n  buildDir: 'build',\r\n  contractsDir: 'contracts',\r\n  testDir: 'test',\r\n  skipContracts: ['contractName.sol'], // Relative paths from contractsDir\r\n  skipTests: ['testFileName.js'], // Relative paths from testDir\r\n  testingTimeOutInSec: 300,\r\n  network: \"none\",\r\n  testingFramework: \"truffle\",\r\n  minimal: false,\r\n  tce: false\r\n}\r\n```\r\n\r\n### 1) Main directories\r\nThese (optional) fields identify relevant project directories.\r\n\r\n| Field | Description | Default Value |\r\n| ------ | ------ |  :----: |\r\n| ```contractsDir```| relative path to the directory of the contracts to be mutated | ```contracts``` |\r\n | ```testDir```| relative path to the directory of the tests to be evaluated | ```test```/```tests``` | \r\n | ```buildDir```| relative path to the directory of the compilation artifacts | ```build```/```out```/```artifacts``` |  |  \r\n\r\n\r\n# CLI Usage 💻\r\n\r\n## Selecting the Mutation Operators\r\n\r\nBefore starting the mutation process you can choose which mutation operators to use:\r\n\r\n| Command       | Description                        | Usage                    | Example                             |\r\n|---------------|------------------------------------|--------------------------|-------------------------------------|\r\n| `list`    | Shows the enabled mutation operators. | `npx/yarn sumo list` | `$ npx sumo list`  |\r\n| `enable`    | Enables one or more mutation operators. If no operator IDs are specified, all of them are enabled. | `npx/yarn sumo enable [...ID]` | `$ npx sumo enable` <br> `$ npx sumo enable AOR BOR` |\r\n| `disable`    | Disables one or more mutation operators. If no operator IDs are specified, all of them are disabled. | `npx/yarn sumo disable [...ID]` | `$ npx sumo disable` <br> `$ npx sumo disable FVR` |\r\n\r\n## Viewing the available mutations\r\n\r\n| Command       | Description                        | Usage                    | Example                             |\r\n|---------------|------------------------------------|--------------------------|-------------------------------------|\r\n| `lookup`    | Generates the mutations and saves them to ./sumo/generated.csv without starting mutation testing. | `npx/yarn sumo lookup` | `$ npx sumo lookup` |\r\n| `mutate`    | Generates the mutations and saves a copy of each `.sol` mutant to  to ./sumo/mutants. | `npx/yarn sumo mutate` | `$ npx sumo mutate` |\r\n\r\n\r\n## Viewing the results\r\nMuSe automatically creates a ```sumo\\results``` folder in the root directory of the project with the following reports: <br/>\r\n* ```results.csv``` Results of the mutation testing process for each mutant in csv format\r\n* ```sumo-log.txt``` Logs info about the mutation testing process\r\n* ```mutations.json``` Results of the mutation testing process for each mutant in json format\r\n* ```\\mutants``` Mutated ```.sol``` contracts generated with ```sumo mutate```\r\n\r\n\r\n# Quickstart ✅\r\nDefault folders creation run (in root folder):\r\n```bash\r\nmkdir -p contracts tests build\r\n```\r\nEnabling TD operator:\r\n```bash\r\nnpx sumo enable TD\r\n```\r\nMutating contracts:\r\n```bash\r\nnpx sumo mutate\r\n```\r\n\r\n##\r\n\r\n\r\n# Mutation Operators 👾\r\n\r\nMuSe includes currently 11 mutation operators.\r\n\r\n## Vulnerability Mutation Operators\r\n\r\n| Operator | Name                                       | Mutation Example                                                                                                                                                                                                                                                                       |\r\n|----------|--------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\r\n| UC       | Unchecked low-level call return value      | ```require(address.call())``` &rarr; ```address.call()```                                                                                                                                                                                                                              |\r\n| US       | Unchecked send                             | ```require(address.send())``` &rarr; ```address.send()```                                                                                                                                                                                                                              |\r\n| UTR      | Unchecked transfer                         | ```require(address.transfer())``` &rarr; ```address.transfer()```                                                                                                                                                                                                                      |\r\n| TX       | Authentication through tx.origin           | ```owner == msg.sender```     &rarr; ```owner == tx.origin```                                                                                                                                                                                                                          |\r\n| DTU      | Delegatecall to untrusted callee           | ```address.delegatecall()``` &rarr; ```function setDelegate(address _addr){addr = _addr} addr.delegatecall()```                                                                                                                                                                        |\r\n| UR1      | Unused return (Assignment)                 | ```_totalSupply = _totalSupply.sub(amount)``` &rarr; ```_totalSupply = 0; _totalSupply.sub(amount)```                                                                                                                                                                                  |\r\n| UR2      | Unused return (Initialization + Assignment)| ```uint length = data.decodeU32()``` &rarr; ```uint length = data.decodeU32()```                                                                                                                                                                                                       |\r\n| TD       | Timestamp dependence                       | ```block.number``` &rarr; ```block.timestamp```                                                                                                                                                                                                                                        |\r\n| IUO      | Integer underflow/overflow                 | ```totalSupply = totalSupply.add(amount)``` &rarr; ```totalSupply = (totalSupply + amount)```                                                                                                                                                                                          |\r\n| USD      | Unprotected self-destruct                  | ```function destroy() private { selfdestruct(payable(owner)); }``` &rarr; ```function destroy() public { selfdestruct(payable(owner)); }```                                                                                                                                            |\r\n| RE       | Reentrancy                                 | ```function withdraw(uint256 amount) public { balances[msg.sender] -= amount; (bool success, ) = msg.sender.call{value: amount}(\"\"); }``` &rarr; ```function withdraw(uint256 amount) public { (bool success, ) = msg.sender.call{value: amount}(\"\"); balances[msg.sender] -= amount; }``` |\r\n\r\n\r\n# Publications 📖\r\n\r\n    @article{iuliano2025automated,\r\n      title={Automated Vulnerability Injection in Solidity Smart Contracts: A Mutation-Based Approach for Benchmark Development},\r\n      author={Iuliano, Gerardo and Allocca, Luigi and Cicalese, Matteo and Di Nucci, Dario},\r\n      journal={arXiv preprint arXiv:2504.15948},\r\n      year={2025}\r\n    }\r\n\r\n","readmeFilename":"README.md","_rev":"1-4882c279ca29f1bd46815a087a18a411"}