Merge pull request #527 from primitivefinance/doc_vulnerability_corpus

vulnerability corpus

README.md

@@ -12,7 +12,7 @@
 **Arbiter** is a framework for stateful Ethereum smart-contract simulation. 
 The framework features an [`ethers-rs`](https://github.com/gakonst/ethers-rs) middleware built on top of [revm](https://github.com/bluealloy/revm) which allows the end user to interact with a sandboxed `revm` instance as if it were an Ethereum node. 
 This provides a familiar interface for interacting with the Ethereum Virtual Machine (EVM), but with unrivaled speed. 
-Furthermore, Arbiter provides containment and management for simulations.
+Furthermore, Arbiter provides containment and management for simulations. For a running list of vulnerabilities found with Arbiter, please see the [Vulnerability Corpu](vulnerability_corpus.md)
 
 ## Overview
 

vulnerability_corpus.md

@@ -0,0 +1,38 @@
+# Vulnerability Corpus
+
+Here is a running list of vulnerabilities that have been found with Arbiter. This list is not exhaustive, but it is a good starting point for understanding how to use Arbiter to find vulnerabilities. Arbiter has a unique ability to detect anomaly behavior in a production-like environment. This can be used to audit mechanism design in smart contract systems as well as detect vulnerabilities in smart contracts.
+
+## Vulnerabilities
+
+
+### Portfolio Rebalancing: Severity - High
+
+This was a critical vulnerability discovered in the [Portfolio Contracts](https://github.com/primitivefinance/portfolio) that we were auditing internally. The bug is described in this [PR](https://github.com/primitivefinance/portfolio_simulations/pull/36/files). To reproduce the vulnerability you can run the following command:
+
+```bash
+git clone https://github.com/primitivefinance/portfolio_simulations.git
+cd portfolio_simulations
+git checkout (bug-found)-invariant-pre-post-swap
+cargo run --release
+```
+The bug was not caught by our [prior audits](https://github.com/primitivefinance/security) and [extensive test suit](https://github.com/primitivefinance/portfolio/tree/main/test). The simulation ran an arbitrageur against the Portfolio AMM and a stochastic price path. The bug was identified after 18,000 swaps. It turns out that that Portfolio pools can reach an edge case where the pool reaches one of the tails of its liquidity distribution and causes the invariant to jump, affecting the price of the trade. This would allow a swapper to take advantage of the mispriced funds and take funds from LPs. With arbiter we were able to run ~20000 swaps with this emulated protocol state in parallel with other parameters in <30s allowing us to discover this anomaly. 
+
+## Rating System 
+
+**Low**: Includes both Non-critical (code style, clarity, syntax, versioning, off-chain monitoring (events, etc) and Low risk (e.g. assets are not at risk: state handling, function incorrect as to spec, issues with comments). 
+
+**Med**: Assets not at direct risk, but the function of the protocol or its availability could be impacted, or leak value with a hypothetical attack path with stated assumptions, but external requirements.
+
+**High**: Assets can be stolen/lost/compromised directly (or indirectly if there is a valid attack path that does not have hand-wavy hypotheticals). These are considered critical issues that should be addressed immediately.
+
+This criteria is based on the [Code4rena](https://docs.code4rena.com/awarding/judging-criteria/severity-categorization) judging criteria.
+
+### Resources for Classifying Vulnerabilities
+- [CVSS](https://www.first.org/cvss/v3.0/user-guide) system.
+- [OWASP](https://owasp.org/www-community/vulnerabilities/) system.
+- [SWC](https://swcregistry.io/) system.
+- [Code4rena](https://docs.code4rena.com/awarding/judging-criteria/severity-categorization)
+
+## Contributing to the Corpus
+
+If you find any vulnerabilities with Arbiter, please submit a pull request to this file with the vulnerability and a description of the vulnerability, a link to the arbiter repo and post mortem and steps to reproduce. If the vulnerability is in the wild and has not yet been patched, please do your best to work with the team responsible for the vulnerability to resolve the vulnerability before disclosing it publicly.