The React Native Developer's Security Guide

A field guide to supply-chain and toolchain risk on macOS

Also available as EPUB

Almost everything written about React Native security is about your users. Secure storage, certificate pinning, jailbreak detection, obfuscation, OWASP MASVS. That material is good and you should read it — but it addresses only half the threat model.

This book is about the other half: the React Native developer.

React Native developers are an unusually good target for a specific structural reason: any RN repository is a polyglot execution environment disguised as a JavaScript project. A single git clone && yarn && pod install && yarn ios runs untrusted, attacker-controllable code in five different runtimes before a line of your app executes. Most developers can name one of them.

Your MacBook holds the source code, the npm publish token, the GitHub PAT, the iOS distribution certificate, the Android upload keystore, the App Store Connect key, the .env with the staging credentials, your browser session cookies, and — increasingly — an AI agent authorized to run shell commands. An attacker who owns your laptop for ten minutes gets all of that and a signed distribution channel to every one of your users. That is a strictly better outcome for them than compromising any single user's phone, and the attack economy has responded accordingly.

---

Who this is for

• React Native developers working on macOS (which is most of them, because iOS builds require Xcode)
• Tech leads deciding what a team is allowed to yarn add
• Anyone who has ever cloned a repository from a recruiter, a client, a Stack Overflow answer, or a GitHub issue titled "reproduction repo"

No security background is assumed. Knowledge of the RN toolchain is.

What this is not

Out of scope: the shipped app and the end user. No secure storage, no cert pinning, no anti-tampering, no MASVS. Not because it doesn't matter — because it is covered exhaustively elsewhere and it is a different threat model with a different asset. See OWASP MASVS and the OWASP Mobile Top 10 for that half.

In scope: the developer, the workstation, the toolchain, the repository, and the CI system that is an extension of all four.

---

Reading paths

"I have two hours and I want the whole model." Read straight through. Parts I–III are the core, closing with a cross-platform chapter on a surface neither the Apple nor Android parts cover; Parts IV–V are the Apple and Android specifics; Part VIII is what to actually do; Part X is Expo-specific and optional if you're on bare React Native.

"I just cloned something sketchy and I'm worried." Appendix C — Triage one-liners → Chapter 31 — Incident response → Chapter 25 — What happens after postinstall.

"Someone sent me a repo and I haven't opened it yet." Appendix B — The safe-clone runbook. Read it before you cd into that directory. Note that opening the folder in your editor can be enough — see Chapter 13.

"I'm hardening a team." Appendix A — File risk atlas → Chapter 28 — Hardening installs → Chapter 29 — Isolation → Chapter 32 — Enforcement.

"Just tell me which files to watch." Appendix A — File risk atlas. It is the single most useful page in the book.

---

Contents

Front matter

• Preface — how to read this, and the defanging policy

Part I — Foundations: why the developer became the target

• 1. Attacker economics: why your laptop outranks your users
• 2. Anatomy of a React Native workstation
• 3. The polyglot trust surface: five runtimes, one git clone
• 4. Who is actually attacking you

Part II — The Node and JavaScript layer

• 5. npm install is remote code execution
• 6. How maintainers fall: phishing, dormancy, and handoff
• 7. Worms: Shai-Hulud and GlassWorm
• 8. nx / s1ngularity: when the malware uses your AI agent
• 9. What lockfiles do and do not protect

Part III — The config files in your repo are programs

• 10. JavaScript config files: Metro, Babel, Expo, ESLint
• 11. Package manager plumbing: npm, Yarn 4.x, and pnpm
• 12. Git itself is an attack surface
• 13. Your editor and your AI agent
• 14. Malicious code in assets: fonts, images, and the files nobody reviews

Part IV — The Apple side

• 15. There is Ruby in your React Native repo
• 16. CocoaPods
• 17. Xcode: build phases, schemes, and XCSSET
• 18. Signing material: what an attacker does with your certificate

Part V — The Android side

• 19. Gradle executes when you open the project
• 20. gradle-wrapper.jar: the binary in your repo
• 21. Keystores and Android secrets

Part VI — Threats outside of the dependency tree

• 22. Your dev server is listening: CVE-2025-11953
• 23. Social engineering developers: fake interviews and ClickFix
• 24. CI is your workstation, extended

Part VII — What happens on macOS after they're in

• 25. The stealer playbook against a developer home directory
• 26. Why macOS does not save you here
• 27. Persistence, and why deleting the package is not remediation

Part VIII — Defense

• 28. Hardening installs
• 29. Isolation and least privilege
• 30. Detection: what to grep for
• 31. Incident response: "I already ran yarn"
• 32. Enforcement

Part X — Expo

• 33. Expo without EAS: prebuild and the native surface
• 34. Expo's dev server: does CVE-2025-11953 reach it?
• 35. Expo's supply chain: are expo-* packages actually safer?

Appendices

• A. The file risk atlas — the reference table
• B. The safe-clone runbook
• C. macOS triage one-liners
• D. Incident timeline, 2015–2026
• E. Glossary
• F. Sources and further reading
• G. Which package manager wins on security
• H. Triaging npm audit in a React Native tree
• I. Contributors

---

A note on dates

Every factual claim in this book is dated and linked to a primary source. This field moves fast enough that undated security advice is actively harmful — a mitigation that was correct in 2023 may be the default in 2026, or may have been bypassed in 2024. Where something was true as of a specific version or date, the book says so.

Content current as of August 2026.

---

The opengrep rules, and how reader feedback becomes book content

The opengrep rule set used to live in rules/ in this repository. It now lives in its own repository — stephanww/rn-dev-security-guide-opengrep — as a companion to the book, not a separate project: 119 opengrep rules across 20 YAML files, each rule keyed to the specific chapter that explains the attack it detects. They are the book's rg/grep "HOW YOU CATCH IT" blocks turned into something you can point at a whole repository, wire into CI, or run as a pre-commit hook — see that repository's README for the full guide, including what the rules deliberately do not catch.

Because every rule is a codified version of a claim the book makes, the two move together even though they live in separate repositories. When a reader reports something — a new technique, a false positive, a correction, a case a rule should have caught and didn't — it goes through the same loop every time:

1. Triage. Is this a narrative gap (the chapter is wrong, outdated, or missing the technique), a detection gap (a rule fires on the wrong thing, or should exist and doesn't), or both? Most real incidents reported this way turn out to be both.
2. Fix the chapter first. Every factual claim in this book is dated and sourced — a correction lands in the relevant chapter, or a new one if the technique doesn't fit an existing one, with a primary source, not a blog post. This happens here, in stephanww/rn-dev-security-guide.
3. Fix or add the rule. Follow the existing pattern documented in the rules repository's README § Extending this rule set: id prefixed rn-security-, a message that names the attacker technique (not just "this looks risky"), a book-reference back to the chapter, confidence/category set honestly rather than optimistically. This happens in stephanww/rn-dev-security-guide-opengrep.
4. Test the rule against a fixture, both directions. This project's own tooling has shipped the same bug shape four times — a check that runs, prints nothing, and reads as safe. Every new or changed rule gets validated against something that should trip it and something legitimate that shouldn't before it's trusted.
5. Log the change. Substantive edits get a line noting the chapter, what changed, and why, so the reasoning doesn't have to be re-derived on the next pass.

Contributions to the book are welcome as issues or pull requests against stephanww/rn-dev-security-guide. Contributions to the rules belong in stephanww/rn-dev-security-guide-opengrep.

---

The defanging policy

This book contains realistic examples of malicious code. Every one of them is structurally real and functionally inert: payloads write a canary file to /tmp instead of exfiltrating anything, and network destinations are either already-burned published indicators or RFC 5737 documentation addresses. Nothing here is copy-pasteable into working malware, and every attack snippet is immediately followed by the command that detects it. Full policy in the preface.

Authorship and license

Written by Stephan Wingerter with Claude (Anthropic) as a writing collaborator.

The book text (book/ and this README) is licensed under Creative Commons Attribution 4.0 International — copy, remix, translate, and reuse it for any purpose, including commercially, as long as you credit the source. The opengrep companion rule set lives in a separate repository, stephanww/rn-dev-security-guide-opengrep, licensed under MIT.