Skip to content

Commit 4766624

Browse files
yosriadyyosriady
authored
Release/0.1.6 (#29)
* deepsec * 0.1.6
1 parent 42c2432 commit 4766624

12 files changed

Lines changed: 1505 additions & 2 deletions

File tree

‎.deepsec/.gitignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
node_modules/
2+
.env*.local
3+
4+
# Scan output — regenerated by `deepsec scan` / `process`. INFO.md
5+
# and SETUP.md (manually edited) stay tracked.
6+
data/*/files/
7+
data/*/runs/
8+
data/*/reports/
9+
data/*/project.json

‎.deepsec/AGENTS.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Agent setup
2+
3+
This is a deepsec scanning workspace. Each registered project has its
4+
own setup prompt at `data/<id>/SETUP.md` — open the relevant one when
5+
asked to set a project up.
6+
7+
## Common tasks
8+
9+
- **Set up a project for scanning**: read `data/<id>/SETUP.md` and
10+
follow it (read `node_modules/deepsec/SKILL.md`, then fill
11+
`data/<id>/INFO.md` from the target codebase).
12+
- **Add a new project**: run `deepsec init-project <root>` — it
13+
scaffolds `data/<id>/` and prints/writes the setup prompt for the
14+
new project.
15+
- **Write a custom matcher** (only after a real true-positive shows you
16+
a pattern worth keeping): read
17+
`node_modules/deepsec/dist/docs/writing-matchers.md`.
18+
19+
## Reference
20+
21+
The deepsec skill is at `node_modules/deepsec/SKILL.md` (after
22+
`pnpm install`). The full docs ship at
23+
`node_modules/deepsec/dist/docs/`.

‎.deepsec/README.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# deepsec
2+
3+
This directory holds the [deepsec](https://www.npmjs.com/package/deepsec)
4+
config for the parent repo. Checked into git so teammates inherit
5+
project context (auth shape, threat model, custom matchers); generated
6+
scan output is gitignored.
7+
8+
Currently configured project: `sdk-react-native` (target: `..`).
9+
10+
## Setup
11+
12+
1. `pnpm install` — installs deepsec.
13+
2. Add an AI Gateway / Anthropic / OpenAI token to `.env.local`. If
14+
you already have `claude` or `codex` CLI logged in on this
15+
machine, you can skip the token for non-sandbox runs (`process` /
16+
`revalidate` / `triage`); deepsec auto-detects and reuses the
17+
subscription. See
18+
`node_modules/deepsec/dist/docs/vercel-setup.md` after install.
19+
3. Open the parent repo in your coding agent (Claude Code, Cursor, …)
20+
and have it follow `data/sdk-react-native/SETUP.md` to fill in
21+
`data/sdk-react-native/INFO.md`.
22+
23+
## Daily commands
24+
25+
```bash
26+
pnpm deepsec scan
27+
pnpm deepsec process --concurrency 5
28+
pnpm deepsec revalidate --concurrency 5 # cuts FP rate
29+
pnpm deepsec export --format md-dir --out ./findings
30+
```
31+
32+
`--project-id` is auto-resolved while there's only one project in
33+
`deepsec.config.ts`. Once you've added a second project, pass
34+
`--project-id sdk-react-native` (or whichever id you want) explicitly.
35+
36+
`scan` is free (regex only). `process` is the AI stage (≈$0.30/file
37+
on Opus by default). Run state goes to `data/sdk-react-native/`.
38+
39+
## Adding another project
40+
41+
To scan another codebase from this same `.deepsec/`:
42+
43+
```bash
44+
pnpm deepsec init-project ../some-other-package # path relative to .deepsec/
45+
```
46+
47+
Appends an entry to `deepsec.config.ts` and writes
48+
`data/<id>/{INFO.md,SETUP.md,project.json}`. Open the new SETUP.md
49+
in your agent to fill in INFO.md.
50+
51+
## Layout
52+
53+
```
54+
deepsec.config.ts Project list (one entry per scanned repo)
55+
data/sdk-react-native/
56+
INFO.md Repo context — checked into git, hand-curated
57+
SETUP.md Agent setup prompt — checked in, deletable
58+
project.json Generated (gitignored)
59+
files/ One JSON per scanned source file (gitignored)
60+
runs/ Run metadata (gitignored)
61+
reports/ Generated markdown reports (gitignored)
62+
AGENTS.md Pointer for coding agents
63+
.env.local Tokens (gitignored)
64+
```
65+
66+
## Docs
67+
68+
After `pnpm install`:
69+
70+
- Skill: `node_modules/deepsec/SKILL.md`
71+
- Full docs: `node_modules/deepsec/dist/docs/{getting-started,configuration,models,writing-matchers,plugins,architecture,data-layout,vercel-setup,faq}.md`
72+
73+
Or browse on
74+
[GitHub](https://github.com/vercel/deepsec/tree/main/docs).

‎.deepsec/data/sdk-react-native/INFO.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# sdk-react-native
2+
3+
## What this codebase does
4+
5+
`@formo/analytics-react-native` — a client-side analytics SDK (npm
6+
library) embedded into third-party React Native dApps. It tracks wallet
7+
events (connect / disconnect / signature / transaction / chain), screen
8+
views, and custom events, batches them in `EventQueue`, and POSTs them
9+
to `https://events.formo.so/v0/raw_events`. Optional Wagmi integration
10+
(`WagmiEventHandler`) auto-captures wallet activity. There is **no
11+
server component** in this repo — it is shipped code that runs inside
12+
other people's apps. Classic web vulns (SQLi, SSRF, server authz) mostly
13+
do not apply; data-handling and supply-chain concerns dominate.
14+
15+
## Auth shape
16+
17+
There is no user/session auth. The only credential is the **`writeKey`**
18+
— a *public, write-only* ingest key intentionally bundled into client
19+
apps and sent as `Authorization: Bearer ${writeKey}` via
20+
`EVENTS_API_REQUEST_HEADER` (`constants/config.ts`). Treat it as
21+
non-secret. The relevant gates instead are:
22+
23+
- `hasOptedOutTracking()` / `CONSENT_OPT_OUT_KEY` + `setConsentFlag` /
24+
`getConsentFlag` / `removeConsentFlag` (`lib/consent`).
25+
- `isBlockedAddress` / `BLOCKED_ADDRESSES` (`utils/address.ts`).
26+
- `validateAddress` (EVM checksum + Solana) before an address is
27+
attached to any event.
28+
29+
## Threat model
30+
31+
Highest impact: (1) PII / sensitive-data exfiltration — the SDK collects
32+
wallet addresses, the **raw message text being signed**, device info,
33+
deep-link URLs, and UTM/referrer attribution; anything that logs,
34+
persists, or ships a private key or full signature secret is critical.
35+
(2) Consent bypass — events generated or flushed after the user opted
36+
out. (3) Supply-chain / untrusted input — host-app-supplied event
37+
`properties` and deep-link URLs flow into the outbound payload.
38+
39+
## Project-specific patterns to flag
40+
41+
- **Signature capture leaking secrets.** `signature()` /
42+
`createSignatureEvent` (`EventFactory`) and `WagmiEventHandler`
43+
mutation tracking store `message` + optional `signatureHash` only.
44+
Flag any path that captures a private key, mnemonic, or the produced
45+
signature itself beyond `signatureHash`.
46+
- **Consent-gate bypass.** Every new event entry point must check
47+
opt-out before `eventQueue.enqueue`, and opt-out must call
48+
`eventQueue.clear()`. Flag new track paths that skip the consent
49+
check.
50+
- **Unvalidated address pass-through.** Addresses attached to events
51+
must go through `validateAddress` / `isBlockedAddress`; flag raw
52+
user/wallet address used directly in a payload.
53+
- **Untrusted properties / deep-link URLs** merged into event payloads
54+
(`parseTrafficSource`, `startDeepLinkCapture`, custom `track`
55+
properties) without sanitization — prototype-pollution or oversized
56+
payload risk.
57+
58+
## Known false-positives
59+
60+
- `writeKey` in the `Bearer` header / bundled in client config — public
61+
write-only key by design, **not** a leaked secret.
62+
- `options.apiHost` overriding the ingest endpoint — intended
63+
self-host/proxy support; not SSRF (runs in the host app's own
64+
process, configured by that app's developer).
65+
- `generateUUID()` using `Math.random()` (`utils/hash.ts`) — analytics
66+
dedup/anon IDs, not security tokens. Acceptable.
67+
- **Minute-rounded `message_id` deduplication** (`generateMessageId` →
68+
`toDateHourMinute`, `lib/event/EventQueue.ts`) — intentional and
69+
**by design**. This is the *canonical cross-SDK + backend dedup
70+
contract* shared with `@formo/analytics` (web) and the
71+
`events.formo.so` ingest pipeline; content-identical events colliding
72+
within the same wall-clock minute is expected behavior, not a bug. Do
73+
**not** flag or "fix" this — including the BUG finding
74+
`other-deduplication-data-loss`. The `message_id` contract may only
75+
change via coordinated web-SDK + backend + RN sign-off, never as an
76+
SDK-local patch.
77+
- Unencrypted `AsyncStorage` / `MemoryStorage` fallback — only stores
78+
anon id + consent flag, non-sensitive by design.
79+
- Hardcoded `SOLANA_SYSTEM_ADDRESSES` / `BLOCKED_ADDRESSES` — public
80+
constants, not secrets.
81+
- Anything under `src/__tests__/` — fixtures and mocks.

‎.deepsec/data/sdk-react-native/SETUP.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Agent setup for `sdk-react-native`
2+
3+
This is a deepsec scanning workspace. Project `sdk-react-native` was just registered
4+
(target: `..`). Setup is incomplete — `data/sdk-react-native/INFO.md`
5+
still has placeholder sections.
6+
7+
## What to do
8+
9+
1. **Read the deepsec skill.** After `pnpm install`, the file is at
10+
`node_modules/deepsec/SKILL.md`. It maps every doc topic to a file
11+
under `node_modules/deepsec/dist/docs/`. Read `getting-started.md`,
12+
`configuration.md`, and `writing-matchers.md` (skim the rest).
13+
14+
2. **Fill in `data/sdk-react-native/INFO.md`.** It's auto-injected into the AI
15+
prompt for every batch — keep it short and selective.
16+
17+
**Length budget: 50–100 lines total.** Verbose context dilutes
18+
signal in the scanner's prompt window. The goal is "what would a
19+
reviewer miss if they didn't read this?", not exhaustive enumeration.
20+
21+
**Per-section rubric**:
22+
- Pick 3–5 representative items per section. **Don't list every
23+
file, helper, or callsite** — pick the patterns.
24+
- Name primitives by their public name (e.g. `withAuthentication`,
25+
`auth.can()`, `isTeamAdmin`). **No line numbers.** Don't enumerate
26+
more than 5 paths in any list.
27+
- Skip generic CWE categories — built-in matchers already cover
28+
"SSRF", "SQL injection", "XSS". Cover what's *project-specific*:
29+
internal auth helpers, custom middleware names, fork-specific
30+
stubs, intended-public endpoints.
31+
- One short paragraph or 3–5 short bullets per section. Not both.
32+
33+
Source material (read in this order, stop when you have enough):
34+
- `../README.md`
35+
- any `AGENTS.md` / `CLAUDE.md` in `..`
36+
- `../package.json` (or `go.mod`, `pyproject.toml`, etc.)
37+
- 5–10 representative code files (entry points, auth helpers) — not
38+
a full code tour.
39+
40+
3. **(Optional) Add custom matchers** for repo-specific patterns the
41+
built-in matchers won't catch. Read
42+
`node_modules/deepsec/dist/docs/writing-matchers.md` first; the
43+
workflow there starts from a confirmed finding and grows the matcher
44+
from it. Don't add matchers speculatively — wait for a real TP.
45+
46+
## When you're done
47+
48+
The user will run:
49+
50+
```bash
51+
pnpm deepsec scan --project-id sdk-react-native
52+
pnpm deepsec process --project-id sdk-react-native
53+
```
54+
55+
You can delete this file once setup is complete.

‎.deepsec/data/sdk-react-native/tech.json‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"tags": [
3+
"github-actions",
4+
"node",
5+
"react"
6+
],
7+
"sentinels": [
8+
"package.json"
9+
],
10+
"detectedAt": "2026-05-16T23:06:59.117Z",
11+
"rootPath": "/Users/yos/sdk-react-native"
12+
}

‎.deepsec/deepsec.config.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
import { defineConfig } from "deepsec/config";
2+
3+
export default defineConfig({
4+
projects: [
5+
{ id: "sdk-react-native", root: ".." },
6+
// <deepsec:projects-insert-above>
7+
],
8+
});

‎.deepsec/package.json‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"name": "deepsec-workspace",
3+
"version": "0.1.0",
4+
"private": true,
5+
"description": "deepsec scanning workspace",
6+
"type": "module",
7+
"workspaces": [],
8+
"packageManager": "pnpm@9.15.4",
9+
"dependencies": {
10+
"deepsec": "^2.0.8"
11+
}
12+
}

0 commit comments

Comments
 (0)