Curating relevant security information is challenging, especially when there’s an overwhelming amount of available data.
Today we introduce Masamune [ma-suh-moo-nay]↗, an open-source utility tool↗ designed for smart contract developers and security researchers. In this post, we’ll delve into what Masamune is, how it works, and how you can use it to improve the security posture of your codebase.
What is Masamune?
Masamune is a utility that allows searching for smart contract security insights. It can identify potential pitfalls from a curated list of audit reports, bug fixes, and technical documentation of various protocols. We make extracting insights easy for all, regardless of security expertise.
Currently, two versions of Masamune are available: V1 and V2. Their differences are listed below:
- V1 relies on plain regex rules, which match the keyword you input against the entire collection of data sources. The advantage of this approach is precision. You’re getting all the results that contain the specific keyword you queried.
- V2 is a regex search enhanced by AI and is still under development. All the data sources are embedded using OpenAI’s embedding↗. We then handle the embeddings via FAISS↗, an open-source library for efficient similarity search. The advantage of this approach is contextual understanding and broader relevance—V2 can interpret the meaning behind your query, providing results that are contextually related, while capturing nuances that plain regex searches would miss.
How Does Masamune Work?
Masamune is designed with simplicity in mind, following the Pareto (80-20) rule↗. This principle suggests that 80% of the results come from 20% of the effort. In the case of Masamune, it means that the tool is optimised to provide the most valuable results with minimal querying effort. This makes it highly effective for modeling the initial stages of the problem you’re trying to solve.
For example, let’s imagine we are developing a protocol that integrates with Uniswap. Using V1, our query would simply be “uniswap”.
Masamune then lists all the results that match “uniswap”, either based on their title or the body text. These results require further details, as our search targeted a broad topic. Let’s say we want to access the second result, “UniswapConfig getters return wrong token config if token config does not exist”. In this particular case, we’re dealing with a finding identified during a Code4rena contest, hence the GitHub issue format. By clicking on the hyperlink↗, we can view all the details of the finding.
This information helps us understand what went wrong, what was the impact of the vulnerability, and how to mitigate it, so that to avoid repeating any similar mistakes.
While a more specific query might provide more accuracy, the regex-based approach in V1 offers a straightforward and efficient way to gather initial data. This simplicity is advantageous in the early stages of development, as it allows for quick identification of generally relevant information.
As a project matures, its complexity inevitably increases. This growing complexity demands not just any quick insights, but context-aware and highly specific ones. The deeper and more intricate the codebase becomes, the more nuanced the queries must be to effectively address the emerging challenges.
To address this need for nuanced queries and more sophisticated insights, we developed V2.
For smart contract developers, staying up-to-date with the latest security issues and bug-fixes is a constant struggle, and it’s hard to know what you don’t know. To ease this learning curve, V2 allows for a more context-aware search using OpenAI embeddings, which widen the results’ breadth. This way, even if you can’t leverage the precision of V1, the additional flexibility of V2 attracts results that would have previously been missed by the same query.
Conclusion
Combining V1’s precise regex capabilities with V2’s context awareness and vector similarity search, Masamune provides an effective way to stay informed about the latest security insights in smart contract development.
The code is open-source, and you can view it on GitHub↗. Additionally, Masamune is deployed via GitHub pages and is available at masamune.app↗.
About Us
Zellic specializes in securing emerging technologies. Our security researchers have uncovered vulnerabilities in the most valuable targets, from Fortune 500s to DeFi giants.
Developers, founders, and investors trust our security assessments to ship quickly, confidently, and without critical vulnerabilities. With our background in real-world offensive security research, we find what others miss.
Contact us↗ for an audit that’s better than the rest. Real audits, not rubber stamps.