docs: add incident report (#1468)

Co-authored-by: Kevin Ingersoll <[email protected]>

docs/pages/_meta.js

@@ -16,6 +16,7 @@ export default {
   reference: "Reference",
   contribute: "Contribute",
   changelog: "Changelog",
+  retrospectives: "Retrospectives",
   version: {
     title: worldPackageJson.version,
     type: "menu",

docs/pages/retrospectives/register-system-vulnerability.mdx

@@ -0,0 +1,55 @@
+# 2023-09-12 `registerSystem` vulnerability
+
+## The bug
+
+Yesterday we discovered a critical vulnerability in MUD v2 alpha versions earlier than `2.0.0-next.8` that would allow an attacker to gain root access to the `World` by registering the `World` contract itself as a system and then exploiting the fact that the `World` treats incoming calls where the caller is its own address as root calls.
+
+To fix this vulnerability we 1. removed the logic that treated external calls by the `World`’s own address as root calls and 2. added an `ERC165` `supportsInterface` check before registering any contract in the World to ensure that each registered contracts actually implements the expected interface, thereby preventing the `World` from being registered as a `System`. The `ERC165` check applies to `System`, `StoreHook`, `SystemHook`, `DelegationControl` and `Module` contracts.
+
+The fix is included in the latest alpha version, `2.0.0-next.8`. We strongly recommend you upgrade your MUD dependencies to this version or later as soon as possible. (An easy way to upgrade MUD to the latest alpha release is to run `pnpm mud set-version --tag next && pnpm install`.)
+
+If you have a persistent contract with a vulnerable MUD version deployed, please reach out to us immediately, so we can work together to upgrade the affected system in your World. We proactively reached out to all known teams using MUD to allow them to patch the bug before disclosing it publicly.
+
+## Links to relevant PRs
+
+- https://github.com/latticexyz/mud/pull/1457
+- https://github.com/latticexyz/mud/pull/1458
+
+## Detailed timeline
+
+All times are in UTC.
+
+- **2023-09-12 17:51:** alvarius, one of the MUD developers, discovered the World vulnerability. He notified other members of Lattice in Discord and we began to plan our course of action.
+- **2023-09-12 18:14:** We agreed on an initial plan. This consisted of:
+  1. Privately reaching out to all developers who we know have deployed MUD projects that are susceptible to this vulnerability.
+  2. Wait until all of those teams have patched the vulnerability.
+  3. Publicly announce we found a vulnerability and patched it.
+- **2023-09-12 19:13:** alvarius began working on the bug patch and a short description of the vulnerability to send to MUD developers.
+- **2023-09-12 19:14:** We assembled a list of MUD developers to contact.
+- **2023-09-12 19:53:** alvarius completed a draft message to send to MUD developers.
+- **2023-09-12 20:06:** alvarius completed the PR to patch the bug.
+- **2023-09-12 21:14:** alvarius merged the PR after review from frolic and dk1a.
+- **2023-09-12 21:27:** We began notifying impacted teams, and updated our in-house game, Sky Strife, to the latest version of MUD.
+- **2023-09-13 8:56:** frolic conducted a Dune query to confirm that we had contacted all impacted teams who have deployed a project using MUD on any mainnet EVM.
+
+## How it was fixed
+
+1. We removed the logic that treated external calls by the `World`'s own address as root calls. See https://github.com/latticexyz/mud/pull/1457 for details on this change.
+2. We added an `ERC165`-based `supportsInterface` check before registering any contract in the World to ensure that each registered contracts actually implements the expected interface, thereby preventing the `World` contract from being registered as a `System`. The `ERC165` check applies to `System`, `StoreHook`, `SystemHook`, `DelegationControl` and `Module` contracts. See https://github.com/latticexyz/mud/pull/1458 for details on this change.
+
+## Lessons learned and next steps
+
+MUD v2 is still in alpha, and we are preparing the contracts for an audit to commence in October. This was fortunately a bug that we could quickly patch, with no known loss of funds incurred for any of our users, or their users. This was our first time discovering and patching a significant security bug in MUD, and we are taking charge to ensure any future instances will run smoothly. Here is a list of next-steps going forward:
+
+1. Setting up internal processes to streamline our incident handling. We’re grateful that everyone on the team jumped in to help resolve this issue within a handful of hours and we want to continue that pattern in future incidents.
+2. Publicly releasing contact information for POC’s to whom you can disclose bugs. In the event of a suspected bug, you can reach [email protected] or one of the following:
+   1. alvarius - Twitter: [\_alvarius](https://twitter.com/_alvarius), Discord: [alvarius](https://discord.com/users/865349544358182932)
+   2. frolic - Twitter: [frolic](https://twitter.com/frolic), Discord: [frolic](https://discord.com/users/79416844720537600)
+   3. vera - Twitter: [virtualelena](https://twitter.com/virtualelena), Discord: [\_v3ra](https://discord.com/users/606316161176567829)
+3. Keeping diligent track of all developers using MUD. Fortunately, we keep an internal database that tracks the majority of developers who are using MUD today, but as our user base grows, this list will grow more complex to maintain. We ask that if you’re building on MUD, someone on your team take an effort to reach either vera, nagual, or kooshaza on our team, who handle external relations. Their contact information is:
+   1. vera - TG: @virtualelena, Discord: @\_v3ra
+   2. nagual - TG: @rafaelMorado, Discord: @raf_0815
+   3. kooshaza - TG: @kooshaza, Discord: @kooshaza
+4. Building a contact list of security experts to contact in the case of urgent security matters.
+
+If you would like to reach us to discuss other mitigation efforts we can take, please reach out at [email protected].