ossf / ossf/oss-crs

docs: propose a macOS / Apple Silicon setup FAQ

Open Beginner friendly
#369 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
159
Forks
33
Avg merge
7h 43m
Merged PRs (30d)
5

Description

Summary

I recently set up and ran OSS-CRS (crs-libfuzzer) end-to-end on an Apple Silicon
Mac and hit several macOS-specific issues that weren't covered in the existing
docs. After working through them to a successful run (full prepare → build-target
→ run pipeline, producing seeds and POVs), I wrote up an FAQ and would like to
contribute it as documentation.

What the FAQ covers
  • Docker Desktop + Rosetta setup for reliably running the amd64 fuzzing images on
    Apple Silicon
  • The three most common errors on Mac and their actual root causes:
    • oss-crs-deps: pull access denied — really a "prepare and build-target hit
      different daemons / local image not present" problem, not a registry issue
    • Fuzzer dies with Killed (exit 137) — ASAN/libFuzzer instability under QEMU
      emulation; resolved by enabling Rosetta
    • cpuset handling — it's a required schema field (can't be deleted), and how
      to set it for a Mac VM
  • oss-crs setup Phase 2 behavior on macOS (the /etc/docker/daemon.json
    cgroup step doesn't apply cleanly) and how to proceed
  • How to confirm a successful run (seeds / POVs under SUBMIT_DIR)
Questions before I open a PR
  1. Would you welcome this as documentation? It's grounded in a confirmed working
    configuration, not speculation.
  2. Where would you prefer it live — e.g. docs/faq-macos.md, a section in an
    existing doc, or somewhere else?
  3. Should I also link it from the README, or do you have a docs index it should
    go into?

Happy to open the PR as soon as you confirm placement. Thanks!

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Review the existing documentation and README to determine the preferred location and linking convention; the proposed path is docs/faq-macos.md. Use the confirmed Docker Desktop, Rosetta, cpuset, setup, and successful-run details from the issue. Done when the FAQ explains the listed macOS problems and how to verify seeds and POVs under SUBMIT_DIR.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker, macos
Domain
devops, documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
74/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.