Merge pull request #3 from trailofbits/fuzzing-new

Add fuzzing chapter

.envrc

@@ -0,0 +1 @@
+use nix

.github/workflows/dictionary.txt

@@ -128,3 +128,178 @@ XSS
 YAML
 Yaml-file
 ZKDocs
+
+# From fuzzing chapter
+.gnca
+.profdata
+.profraw
+03-asan
+04-env
+0x61
+0x63
+10-libfuzzer
+1000s
+100s
+10k
+10⁶
+16TB
+1k
+20TB
+25k
+2x
+AFL_PIZZA_MODE
+ASan
+AUTODICTIONARIES
+Additional
+AddressSanitizer
+Base64
+Bazel
+CMake-based
+CMakeLists
+CNCF
+CNCF-Fuzzing
+CVE-2021-3156
+CVE-2023-4863
+ChatGPT
+Codebases
+DigitalOcean
+Dockerfile
+Dockerhub
+Entrypoint
+Fuzzers
+GCC-compatible
+Hongfuzz
+Instrumentations
+LLM
+LLMs
+LLVM
+LLVM's
+LLVM-based
+LLVMFuzzerTestOneInput
+LTO
+LibAFL
+LiveOverflow
+MSVC
+Mitigations
+OpenAI's
+OpenSSL
+PNG
+PRNG
+Parsers
+Protobuf
+Pseudocode
+SUT
+SUTs
+SanitizerCoverage
+Spectre
+Sudo
+TCP
+TLS
+TODO
+UTF-8
+UndefinedBehaviorSanitizer
+VM
+VMs
+Walkthrough
+XCode
+addresssanitizer
+afl
+afl-whatsup
+aflpp
+argc
+argv
+as
+LLVM
+asan
+big-endian
+bitstring
+blackbox
+bootloader
+c-cpp
+cargo-binutils
+cargo-crate-ogg
+cargo-geiger
+checksums
+close_fd_mask
+cloudexec
+cloudinit
+cmake-based-project
+code-coverage-using-gcov-and-gcovr
+code-coverage-using-llvm-sanitizercoverage
+codecs
+concat
+cryptographic
+customFigure
+de
+demangler
+deserialize
+deserializers
+durations
+entrypoint
+enum
+facto
+faq
+faq-fuzzily-asked-questions
+forkserver
+function
+fuzzer's
+fuzzer-defined
+fuzzer-options
+fuzzers
+gcc_plugin
+gcov
+gcovr
+gnuplot
+graybox
+instrumentations
+interestingness
+intro-os
+introduction-to-fuzzers
+iteratively
+lcov
+libFuzzer's
+libFuzzer-compatible
+libFuzzer-like
+libFuzzer-style
+libfuzzer
+libfuzzer-sys
+libpng
+llvm-cov
+llvm-tools-preview
+max_len=4000
+mitigations
+mutators
+nondeterministically
+ogg
+optimizing-the-fuzzer-enable-persistent-mode
+parsers
+performant
+permalink
+precompiled
+protobuf
+pseudocode
+rawHtml
+readd
+reconfigures
+reproducibility
+resourceFigure
+rustfilt
+rustup
+standard-input-stdin-fuzzing
+stdin
+struct
+structs
+subcommand
+subdirectory
+sudo
+sut-patching-overcoming-obstacles
+th
+toolchain
+tradeoff
+ubuntu
+unparsable
+uplevel
+version
+when-should-i-use-which-fuzzer
+x64_64
+

.github/workflows/hugo.yml

@@ -30,7 +30,7 @@ jobs:
   build:
     runs-on: ubuntu-latest
     env:
-      HUGO_VERSION: 0.108.0
+      HUGO_VERSION: 0.122.0
     steps:
       - name: Install Hugo CLI
         run: |

.github/workflows/markdown.yml

@@ -21,12 +21,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v3
-    - uses: DavidAnson/markdownlint-cli2-action@v9
+    - uses: DavidAnson/markdownlint-cli2-action@v15
       with:
-        command: config
-        globs: |
-         .github/workflows/.markdownlint.jsonc
-         **/*.md
+        globs: "**/*.md"
   # Spellcheck Markdown files using `retext` and `remark`
   # Uses: a custom dictionary file
   spellcheck:

.github/workflows/preview.yml

@@ -0,0 +1,55 @@
+# .github/workflows/preview.yml
+name: Deploy PR previews
+
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - closed
+
+concurrency: preview-${{ github.ref }}
+
+permissions:
+  pull-requests: write
+
+# Default to bash
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  # Build job
+  build-deploy:
+    runs-on: ubuntu-latest
+    env:
+      HUGO_VERSION: 0.122.0
+    steps:
+      - name: Install Hugo CLI
+        run: |
+          wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
+          && sudo dpkg -i ${{ runner.temp }}/hugo.deb
+      - name: Install Dart Sass Embedded
+        run: sudo snap install dart-sass-embedded
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          submodules: recursive
+      - name: Install Node.js dependencies
+        run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
+      - name: Build with Hugo
+        env:
+          # For maximum backward compatibility with Hugo modules
+          HUGO_ENVIRONMENT: production
+          HUGO_ENV: production
+        run: |
+          hugo \
+            --minify \
+            --baseURL "https://trailofbits.github.io/testing-handbook-preview/pr-preview/pr-${{ github.event.number }}/"
+      - name: Deploy preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: ./public/
+          token: ${{ secrets.TESTING_HANDBOOK_PREVIEW_REPO }}
+          deploy-repository: trailofbits/testing-handbook-preview

.gitignore

@@ -6,3 +6,5 @@ node_modules/*
 
 .hugo_build.lock
 resources/
+
+.direnv/

.markdownlint-cli2.jsonc

@@ -0,0 +1,3 @@
+{
+      "ignores": ["content/docs/fuzzing/**", "themes/book/**", "node_modules/**"]
+}

README.md

@@ -89,7 +89,7 @@ Your browser will be automatically refreshed with changes whenever you save a fi
 
 6. Edit, add, and create pull requests to merge your changes into `main`.
 
-7. ❗Keep in mind that when you merge your PR into `main`, the content goes live in https://appsec.guide.
+7. ❗Keep in mind that when you merge your PR into `main`, the content goes live in <https://appsec.guide>.
     Our current policy forces at least one review before merging.
 
 8. For updates to the home page, edit [content/_index.md](content/_index.md)
@@ -117,3 +117,43 @@ Your browser will be automatically refreshed with changes whenever you save a fi
 - Familiarize yourself with the [Hugo Book theme](https://hugo-book-demo.netlify.app/)
 as it has a couple of nice features (buttons, etc.)
 - Reach out in [#testing-handbook](https://empirehacking.slack.com/archives/C06CSLSQAMB) Empire Hacking Slack if you have any questions.
+
+## Editing
+
+### Writing Guidelines
+
+- The term "Testing Handbook" should be capitalized any time it appears on the website (whether in a header/subheader or running text),
+since it is the title of a document. But if you'd like to avoid the capitalization because it looks strange, you can substitute
+"Testing Handbook" for "this handbook" (since it's clear enough what the title of the handbook is).
+
+### Workflow: From Google Docs
+
+1. Make your document viewable via a link share.
+2. Create a Google account or use your private one (If you use this method, then your document should be regarded as public, but unpublished).
+3. Install [Docs to Markdown](https://workspace.google.com/marketplace/app/docs_to_markdown/700168918607).
+This addon works better than pandoc.
+4. Open the document and make a copy.
+5. Open the copy and run the Addon.
+6. Export the markdown and apply fixes:
+   - Search for occurences of `<code>` or `<strong>` or any other html tags
+   - Replace HTML tables with markdown ones (<https://jmalarcon.github.io/markdowntables/>)
+   - If you split your document, fix internal links.
+   - Add missing images.
+   - Fix `&lt;`, …, “, ’
+   - Adjust markdown captions ## -> #
+   - Verify missing formatting in PRO TIPs
+   - . at the end of fig captions?
+   - Note that index bundles do not use the "slug"
+
+### Custom enviornments
+
+```md
+{{< customFigure "Caption" >}}
+{{< /customFigure >}}
+
+{{< resourceFigure "cov1.png" >}}
+{{< /resourceFigure >}}
+
+{{< hint info >}}
+{{< /hint >}}
+```