Reorganize book, re-add medusa docs

.github/workflows/deploy.yml

@@ -27,7 +27,11 @@ jobs:
         run: |
           cargo install --git https://github.com/montyly/mdBook.git mdbook || true
       - name: Build artifacts
-        run: mdbook build
+        run: |
+          mv src/program-analysis/medusa/docs/src/ tmp-medusa
+          rm -rf src/program-analysis/medusa
+          mv tmp-medusa src/program-analysis/medusa
+          mdbook build
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:

.github/workflows/echidna.yml

@@ -4,15 +4,15 @@ on:
   push:
     paths:
       - ".github/workflows/echidna.yml"
-      - "program-analysis/echidna/**/*.sol"
-      - "program-analysis/echidna/**/*.yml"
+      - "src/program-analysis/echidna/**/*.sol"
+      - "src/program-analysis/echidna/**/*.yml"
     branches:
       - master
   pull_request:
     paths:
       - ".github/workflows/echidna.yml"
-      - "program-analysis/echidna/**/*.sol"
-      - "program-analysis/echidna/**/*.yml"
+      - "src/program-analysis/echidna/**/*.sol"
+      - "src/program-analysis/echidna/**/*.yml"
   schedule:
     # run CI every day even if no PRs/merges occur
     - cron: "0 12 * * *"
@@ -27,25 +27,25 @@ jobs:
       matrix:
         include:
           - name: Exercise 1
-            workdir: program-analysis/echidna/exercises/exercise1/
+            workdir: src/program-analysis/echidna/exercises/exercise1/
             files: solution.sol
             contract: TestToken
             outcome: failure
             expected: 'echidna_test_balance:\s*failed'
           - name: Exercise 2
-            workdir: program-analysis/echidna/exercises/exercise2/
+            workdir: src/program-analysis/echidna/exercises/exercise2/
             files: solution.sol
             contract: TestToken
             outcome: failure
             expected: 'echidna_no_transfer:\s*failed'
           - name: Exercise 3
-            workdir: program-analysis/echidna/exercises/exercise3/
+            workdir: src/program-analysis/echidna/exercises/exercise3/
             files: solution.sol
             contract: TestToken
             outcome: failure
             expected: 'echidna_test_balance:\s*failed'
           - name: Exercise 4
-            workdir: program-analysis/echidna/exercises/exercise4/
+            workdir: src/program-analysis/echidna/exercises/exercise4/
             files: solution.sol
             config: config.yaml
             contract: TestToken
@@ -76,56 +76,56 @@ jobs:
             outcome: failure
             expected: 'testPoolBalance():\s*failed'
           - name: TestToken
-            workdir: program-analysis/echidna/example/
+            workdir: src/program-analysis/echidna/example/
             files: testtoken.sol
             contract: TestToken
             outcome: failure
             expected: 'echidna_balance_under_1000:\s*failed'
           - name: Gas estimation
-            workdir: program-analysis/echidna/example/
+            workdir: src/program-analysis/echidna/example/
             files: gas.sol
             config: gas.yaml
             outcome: success
             expected: "f(42,123,"
             flaky: true
           - name: Multi
-            workdir: program-analysis/echidna/example/
+            workdir: src/program-analysis/echidna/example/
             files: multi.sol
             config: filter.yaml
             outcome: failure
             expected: 'echidna_state4:\s*failed'
           - name: Assert
-            workdir: program-analysis/echidna/example/
+            workdir: src/program-analysis/echidna/example/
             files: assert.sol
             config: assert.yaml
             outcome: failure
             expected: 'inc(uint256):\s*failed'
           - name: PopsicleBroken
-            workdir: program-analysis/echidna/example/
+            workdir: src/program-analysis/echidna/example/
             files: PopsicleBroken.sol
             solc-version: 0.8.4
             config: Popsicle.yaml
             contract: PopsicleBroken
             outcome: failure
             expected: 'totalBalanceAfterTransferIsPreserved(address,uint256):\s*failed'
           - name: PopsicleFixed
-            workdir: program-analysis/echidna/example/
+            workdir: src/program-analysis/echidna/example/
             files: PopsicleFixed.sol
             solc-version: 0.8.4
             config: Popsicle.yaml
             contract: PopsicleFixed
             outcome: success
             expected: 'totalBalanceAfterTransferIsPreserved(address,uint256):\s*passing'
           - name: TestDepositWithPermit
-            workdir: program-analysis/echidna/example/
+            workdir: src/program-analysis/echidna/example/
             files: TestDepositWithPermit.sol
             solc-version: 0.8.0
             config: testdeposit.yaml
             contract: TestDepositWithPermit
             outcome: success
             expected: 'testERC20PermitDeposit(uint256):\s*passing'
           - name: MultiABI
-            workdir: program-analysis/echidna/example/
+            workdir: src/program-analysis/echidna/example/
             files: allContracts.sol
             solc-version: 0.8.0
             config: allContracts.yaml

.github/workflows/lint_format.yml

@@ -25,12 +25,12 @@ jobs:
         run: |
           npm ci
 
-      - name: Remove Medusa uncessary files
+      - name: Remove unnecessary Medusa files
         run: |
-          rm -rf program-analysis/medusa/chain
-          rm -rf program-analysis/medusa/compilation
-          rm -rf program-analysis/medusa/fuzzing
-          rm program-analysis/medusa/docs/theme/highlight.js
+          rm -rf src/program-analysis/medusa/chain
+          rm -rf src/program-analysis/medusa/compilation
+          rm -rf src/program-analysis/medusa/fuzzing
+          rm src/program-analysis/medusa/docs/theme/highlight.js
 
       - name: Run lint
         run: |

.github/workflows/manticore.yml

@@ -4,13 +4,13 @@ on:
   push:
     paths:
       - ".github/workflows/manticore.yml"
-      - "program-analysis/manticore/**/*.py"
+      - "src/program-analysis/manticore/**/*.py"
     branches:
       - master
   pull_request:
     paths:
       - ".github/workflows/manticore.yml"
-      - "program-analysis/manticore/**/*.py"
+      - "src/program-analysis/manticore/**/*.py"
   schedule:
     # run CI every day even if no PRs/merges occur
     - cron: "0 12 * * *"
@@ -33,4 +33,4 @@ jobs:
           solc-select use 0.5.11
       - name: Run Tests
         run: |
-          bash program-analysis/manticore/scripts/gh_action_test.sh
+          bash src/program-analysis/manticore/scripts/gh_action_test.sh

.github/workflows/medusa.yml

@@ -4,15 +4,15 @@ on:
   push:
     paths:
       - ".github/workflows/medusa.yml"
-      - "program-analysis/echidna/**/*.sol"
-      - "program-analysis/echidna/**/*.yml"
+      - "src/program-analysis/echidna/**/*.sol"
+      - "src/program-analysis/echidna/**/*.yml"
     branches:
       - master
   pull_request:
     paths:
       - ".github/workflows/medusa.yml"
-      - "program-analysis/echidna/**/*.sol"
-      - "program-analysis/echidna/**/*.yml"
+      - "src/program-analysis/echidna/**/*.sol"
+      - "src/program-analysis/echidna/**/*.yml"
   schedule:
     # run CI every day even if no PRs/merges occur
     - cron: "0 12 * * *"
@@ -27,25 +27,25 @@ jobs:
       matrix:
         include:
           - name: Exercise 1
-            workdir: program-analysis/echidna/exercises/exercise1/
+            workdir: src/program-analysis/echidna/exercises/exercise1/
             files: solution.sol
             contract: TestToken
             outcome: failure
             expected: 'echidna_test_balance()\" failed after the following call sequence'
           - name: Exercise 2
-            workdir: program-analysis/echidna/exercises/exercise2/
+            workdir: src/program-analysis/echidna/exercises/exercise2/
             files: solution.sol
             contract: TestToken
             outcome: failure
             expected: 'echidna_no_transfer()\" failed after the following call sequence'
           - name: Exercise 3
-            workdir: program-analysis/echidna/exercises/exercise3/
+            workdir: src/program-analysis/echidna/exercises/exercise3/
             files: solution.sol
             contract: TestToken
             outcome: failure
             expected: 'echidna_test_balance()\" failed after the following call sequence'
           - name: Exercise 4
-            workdir: program-analysis/echidna/exercises/exercise4/
+            workdir: src/program-analysis/echidna/exercises/exercise4/
             files: solution.sol
             contract: TestToken
             outcome: failure
@@ -75,49 +75,49 @@ jobs:
           #   outcome: failure
           #   expected: 'testPoolBalance():\s*failed'
           - name: TestToken
-            workdir: program-analysis/echidna/example/
+            workdir: src/program-analysis/echidna/example/
             files: testtoken.sol
             contract: TestToken
             outcome: failure
             expected: 'echidna_balance_under_1000()\" failed after the following call sequence'
           - name: Multi
-            workdir: program-analysis/echidna/example/
+            workdir: src/program-analysis/echidna/example/
             files: multi.sol
             contract: C
             config: filter.yaml
             outcome: failure
             expected: 'echidna_state4()\" failed after the following call sequence'
           - name: Assert
-            workdir: program-analysis/echidna/example/
+            workdir: src/program-analysis/echidna/example/
             files: assert.sol
             config: assert.yaml
             contract: Incrementor
             outcome: failure
             expected: 'inc(uint256)\" resulted in an assertion failure after the following call sequence'
           - name: PopsicleBroken
-            workdir: program-analysis/echidna/example/
+            workdir: src/program-analysis/echidna/example/
             files: PopsicleBroken.sol
             solc-version: 0.8.4
             contract: PopsicleBroken
             outcome: failure
             expected: 'PopsicleBroken.totalBalanceAfterTransferIsPreserved(address,uint256)\" resulted in an assertion failure after the following call sequence'
           - name: PopsicleFixed
-            workdir: program-analysis/echidna/example/
+            workdir: src/program-analysis/echidna/example/
             files: PopsicleFixed.sol
             solc-version: 0.8.4
             contract: PopsicleFixed
             outcome: success
             expected: '\[PASSED\] Assertion Test: PopsicleFixed.totalBalanceAfterTransferIsPreserved(address,uint256)'
           - name: TestDepositWithPermit
-            workdir: program-analysis/echidna/example/
+            workdir: src/program-analysis/echidna/example/
             files: TestDepositWithPermit.sol
             solc-version: 0.8.0
             config: testdeposit.yaml
             contract: TestDepositWithPermit
             outcome: success
             expected: '\[PASSED\] Assertion Test: TestDepositWithPermit.testERC20PermitDeposit(uint256)'
           # - name: MultiABI
-          #   workdir: program-analysis/echidna/example/
+          #   workdir: src/program-analysis/echidna/example/
           #   files: allContracts.sol
           #   solc-version: 0.8.0
           #   config: allContracts.yaml

.github/workflows/slither.yml

@@ -4,13 +4,13 @@ on:
   push:
     paths:
       - ".github/workflows/slither.yml"
-      - "program-analysis/slither/**/*.py"
+      - "src/program-analysis/slither/**/*.py"
     branches:
       - master
   pull_request:
     paths:
       - ".github/workflows/slither.yml"
-      - "program-analysis/slither/**/*.py"
+      - "src/program-analysis/slither/**/*.py"
   schedule:
     # run CI every day even if no PRs/merges occur
     - cron: "0 12 * * *"
@@ -31,4 +31,4 @@ jobs:
           pip install solc-select
       - name: Run Tests
         run: |
-          bash program-analysis/slither/scripts/gh_action_test.sh
+          bash src/program-analysis/slither/scripts/gh_action_test.sh

.gitignore

@@ -1,2 +1,3 @@
 .DS_Store
 node_modules
+/book/

.gitmodules

@@ -1,3 +1,3 @@
-[submodule "program-analysis/medusa"]
-	path = program-analysis/medusa
+[submodule "src/program-analysis/medusa"]
+	path = src/program-analysis/medusa
 	url = https://github.com/crytic/medusa.git

CODEOWNERS

@@ -1,8 +1,8 @@
-*                                  @montyly
-/development-guidelines/           @0xicingdeath 
-/program-analysis/echidna/         @ggrieco-tob
-/not-so-smart-contracts/algorand/  @S3v3ru5
-/not-so-smart-contracts/cairo/     @technovision99 
-/not-so-smart-contracts/cosmos/    @GrosQuildu 
-/not-so-smart-contracts/substrate/ @0xicingdeath 
-/learn_evm/                        @bohendo
+*                                      @montyly
+/src/development-guidelines/           @0xicingdeath
+/src/program-analysis/echidna/         @ggrieco-tob
+/src/not-so-smart-contracts/algorand/  @S3v3ru5
+/src/not-so-smart-contracts/cairo/     @technovision99
+/src/not-so-smart-contracts/cosmos/    @GrosQuildu
+/src/not-so-smart-contracts/substrate/ @0xicingdeath
+/src/learn_evm/                        @bohendo

README.md

@@ -6,36 +6,36 @@ Brought to you by [Trail of Bits](https://www.trailofbits.com/), this repository
 
 **Table of Contents:**
 
-- [Development Guidelines](./development-guidelines)
-  - [Code Maturity](./development-guidelines/code_maturity.md): Criteria for developers and security engineers to use when evaluating a codebase’s maturity
-  - [High-Level Best Practices](./development-guidelines/guidelines.md): Best practices for all smart contracts
-  - [Incident Response Recommendations](./development-guidelines/incident_response.md): Guidelines for creating an incident response plan
-  - [Secure Development Workflow](./development-guidelines/workflow.md): A high-level process to follow during code development
-  - [Token Integration Checklist](./development-guidelines/token_integration.md): What to check when interacting with arbitrary tokens
-- [Learn EVM](./learn_evm): Technical knowledge about the EVM
-  - [EVM Opcodes](./learn_evm/evm_opcodes.md): Information on all EVM opcodes
-  - [Transaction Tracing](./learn_evm/tracing.md): Helper scripts and guidance for generating and navigating transaction traces
-  - [Arithmetic Checks](./learn_evm/arithmetic-checks.md): A guide to performing arithmetic checks in the EVM
-  - [Yellow Paper Guidance](./learn_evm/yellow-paper.md): Symbol reference for easier reading of the Ethereum yellow paper
-  - [Forks <> EIPs](./learn_evm/eips_forks.md): Summaries of the EIPs included in each Ethereum fork
-    - [Forks <> CIPs](./learn_evm/cips_forks.md): Summaries of the CIPs and EIPs included in each Celo fork _(EVM-compatible chain)_
-    - [Upgrades <> TIPs](./learn_evm/tips_upgrades.md): Summaries of the TIPs included in each TRON upgrade _(EVM-compatible chain)_
-    - [Forks <> BEPs](./learn_evm/beps_forks.md): Summaries of the BEPs included in each BSC fork _(EVM-compatible chain)_
-- [Not So Smart Contracts](./not-so-smart-contracts): Examples of common smart contract issues, complete with descriptions, examples, and recommendations
-  - [Algorand](./not-so-smart-contracts/algorand)
-  - [Cairo](./not-so-smart-contracts/cairo)
-  - [Cosmos](./not-so-smart-contracts/cosmos)
-  - [Substrate](./not-so-smart-contracts/substrate)
-  - [Solana](./not-so-smart-contracts/solana)
-- [Program Analysis](./program-analysis): Using automated tools to secure contracts
-  - [Echidna](./program-analysis/echidna): A fuzzer that checks your contract's properties
-  - [Slither](./program-analysis/slither): A static analyzer with both CLI and scriptable interfaces
-  - [Manticore](./program-analysis/manticore): A symbolic execution engine that proves the correctness of properties
+- [Development Guidelines](./src/development-guidelines)
+  - [Code Maturity](./src/development-guidelines/code_maturity.md): Criteria for developers and security engineers to use when evaluating a codebase’s maturity
+  - [High-Level Best Practices](./src/development-guidelines/guidelines.md): Best practices for all smart contracts
+  - [Incident Response Recommendations](./src/development-guidelines/incident_response.md): Guidelines for creating an incident response plan
+  - [Secure Development Workflow](./src/development-guidelines/workflow.md): A high-level process to follow during code development
+  - [Token Integration Checklist](./src/development-guidelines/token_integration.md): What to check when interacting with arbitrary tokens
+- [Learn EVM](./src/learn_evm): Technical knowledge about the EVM
+  - [EVM Opcodes](./src/learn_evm/evm_opcodes.md): Information on all EVM opcodes
+  - [Transaction Tracing](./src/learn_evm/tracing.md): Helper scripts and guidance for generating and navigating transaction traces
+  - [Arithmetic Checks](./src/learn_evm/arithmetic-checks.md): A guide to performing arithmetic checks in the EVM
+  - [Yellow Paper Guidance](./src/learn_evm/yellow-paper.md): Symbol reference for easier reading of the Ethereum yellow paper
+  - [Forks <> EIPs](./src/learn_evm/eips_forks.md): Summaries of the EIPs included in each Ethereum fork
+    - [Forks <> CIPs](./src/learn_evm/cips_forks.md): Summaries of the CIPs and EIPs included in each Celo fork _(EVM-compatible chain)_
+    - [Upgrades <> TIPs](./src/learn_evm/tips_upgrades.md): Summaries of the TIPs included in each TRON upgrade _(EVM-compatible chain)_
+    - [Forks <> BEPs](./src/learn_evm/beps_forks.md): Summaries of the BEPs included in each BSC fork _(EVM-compatible chain)_
+- [Not So Smart Contracts](./src/not-so-smart-contracts): Examples of common smart contract issues, complete with descriptions, examples, and recommendations
+  - [Algorand](./src/not-so-smart-contracts/algorand)
+  - [Cairo](./src/not-so-smart-contracts/cairo)
+  - [Cosmos](./src/not-so-smart-contracts/cosmos)
+  - [Substrate](./src/not-so-smart-contracts/substrate)
+  - [Solana](./src/not-so-smart-contracts/solana)
+- [Program Analysis](./src/program-analysis): Using automated tools to secure contracts
+  - [Echidna](./src/program-analysis/echidna): A fuzzer that checks your contract's properties
+  - [Slither](./src/program-analysis/slither): A static analyzer with both CLI and scriptable interfaces
+  - [Manticore](./src/program-analysis/manticore): A symbolic execution engine that proves the correctness of properties
   - For each tool, this training material provides:
     - A theoretical introduction, an API walkthrough, and a set of exercises
     - Exercises that take approximately two hours to gain practical understanding
-- [Resources](./resources): Assorted online resources
-  - [Trail of Bits Blog Posts](./resources/tob_blogposts.md): A list of blockchain-related blog posts created by Trail of Bits
+- [Resources](./src/resources): Assorted online resources
+  - [Trail of Bits Blog Posts](./src/resources/tob_blogposts.md): A list of blockchain-related blog posts created by Trail of Bits
 
 # License
 

book.toml

@@ -2,7 +2,7 @@
 authors = ["Trail of Bits"]
 language = "en"
 multilingual = false
-src = "."
+src = "src"
 title = "Building Secure Contracts"
 description = "This repository, brought to you by Trail of Bits, outlines our guidelines and best practices to write secure smart contracts."
 logo = "static/TOB_Black.svg"