Sign In

auditreach-cli

Package Overview
Dependencies
Maintainers
2
Versions
8
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

auditreach-cli - npm Package Compare versions

Comparing version
0.2.2
 to
0.2.3
+1
-1
package.json
{
"name": "auditreach-cli",
"version": "0.2.2",
"version": "0.2.3",
"description": "Official-API-only, BYOK CLI for researching Reddit and YouTube with your own API keys and a tamper-evident, hash-chained audit log -- built for AI agents and compliance teams that can't rely on cookie-based scraping or shared credential pools.",

@@ -5,0 +5,0 @@ "type": "module",

+25
-23
README.md

@@ -84,3 +84,3 @@ <div align="center">

[Agent-Reach](https://github.com/Panniantong/Agent-Reach) is not a bad tool. It has real traction (55k+ stars) because cookie-based scraping genuinely covers more ground than any official API does today, at zero API cost. But "covers more ground" and "an agency's client can pass a compliance review" are two different bars, and nothing was built specifically to clear the second one.
[Agent-Reach](https://github.com/Panniantong/Agent-Reach) is not a bad tool. It has real traction (65k+ stars) because cookie-based scraping genuinely covers more ground than any official API does today, at zero API cost. But "covers more ground" and "an agency's client can pass a compliance review" are two different bars, and nothing was built specifically to clear the second one.

@@ -93,14 +93,14 @@ auditreach is the CLI we wished existed instead. It talks to Reddit and YouTube only through their official, documented APIs, using your own API keys -- never a shared pool -- and every single query writes a hash-chained entry to a local audit log: which platform, which endpoint, which scope, and a plain-language line explaining the consent/ToS basis for that specific call. No cookie import. No session-token reuse. No code path that could even pretend to be a logged-in human.

| | **auditreach** | **Agent-Reach** | **snoowrap** |
| ---------------------------- | ------------------------------ | ------------------------------------------------------- | --------------------------------------------------- |
| Access model | Official API only, BYO-key | Cookie/session import, "zero API fees" | Official API, BYO-key |
| Platform coverage (v0.1) | Reddit, YouTube | Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu | Reddit only |
| Consent/audit log | Hash-chained, per-query, local | None | None |
| Maintenance status | Active (this release) | Active, 55k stars | **Archived** since Feb 2023 |
| License | Apache 2.0 | MIT | MIT |
| Runtime deps (Reddit client) | 0 -- native `fetch` | n/a (Python, browser-session based) | `request`, `request-promise`, `ws` (all deprecated) |
| | **auditreach** | **Agent-Reach** | **snoowrap** |
| ----------------------------- | ------------------------------- | --------------------------------------------------------- | ------------------------------------------------------ |
| Access model | Official API only, BYO-key | Cookie/session import, "zero API fees" | Official API, BYO-key |
| Platform coverage | Reddit, YouTube | Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu | Reddit only |
| Consent/audit log | Hash-chained, per-query, local | None | None |
| Maintenance status | Active (this release) | Active, 65k+ stars | **Archived** since Feb 2023 |
| License | Apache 2.0 | MIT | MIT |
| Runtime deps (Reddit client) | 0 -- native `fetch` | n/a (Python, browser-session based) | `request`, `request-promise`, `ws` (all deprecated) |
Numbers measured directly against each repo's public GitHub metadata and, for the dependency comparison, against `snoowrap`'s own published `package.json` as of this writing -- reproducible by anyone with `gh api repos/<owner>/<repo>`.
We started building auditreach's Reddit client on top of `snoowrap`, the most-used Reddit API wrapper in the Node ecosystem. Installing it pulled in `request`, `request-promise`, `form-data`, and `har-validator` -- a dependency chain with **4 CRITICAL** and multiple HIGH severity advisories, none of which snoowrap can fix because the project has been archived since 2023. We rewrote the Reddit client as a direct `fetch`-based OAuth2 client against Reddit's own documented REST endpoints instead: same functionality, zero of those CVEs, zero extra runtime dependencies. `npm audit --audit-level=high` on this repo returns clean.
We started building auditreach's Reddit client on top of `snoowrap`, the most-used Reddit API wrapper in the Node ecosystem. Installing it pulls in `request`, `request-promise`, `form-data`, and `har-validator` -- a dependency chain that currently carries 2 CRITICAL, 2 HIGH, and 5 moderate severity advisories (9 total, per `npm audit`), none of which snoowrap can fix because the project has been archived since 2023. We rewrote the Reddit client as a direct `fetch`-based OAuth2 client against Reddit's own documented REST endpoints instead: same functionality, none of those CVEs, zero extra runtime dependencies for that client. See [Security](#security) for auditreach's own current `npm audit` status.

@@ -174,3 +174,3 @@ ## What it does

| Flag | Description |
| ------------------------- | ----------------------------------------------------------------------------------------------- |
| ------------------------- | ------------------------------------------------------------------------------------------------ |
| `--platform <platform>` | `reddit` \| `youtube` (required) |

@@ -195,7 +195,7 @@ | `--query <query>` | search query (required) |

| Flag | Description |
| ----------------------- | -------------------------------------------------------------------------------------------------- |
| ----------------------- | --------------------------------------------------------------------------------------------------- |
| `--platform <platform>` | `reddit` \| `youtube` (required) |
| `--clear` | delete stored credentials for this platform |
| `--verify` | verify stored credentials are valid without running a search (no results file, no audit-log entry) |
| `--json` | print structured JSON to stdout instead of human-readable output |
| `--json` | with `--verify`, print a structured JSON result instead of human-readable text |

@@ -209,3 +209,3 @@ node dist/cli.js auth --platform reddit --verify

| Flag | Description |
| --------------- | ---------------------------------------------------------------------------- |
| --------------- | ----------------------------------------------------------------------------- |
| `--path <path>` | path to the audit log file (defaults to `./auditreach.log.jsonl` if omitted) |

@@ -220,3 +220,3 @@

| Tool | Equivalent to | Notes |
| ------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------- |
| ------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `search` | `auditreach search --json` | Same parameters: platform, query, subreddit/channel, since, maxResults, before/after |

@@ -237,3 +237,3 @@ | `auth_status` | `auditreach auth --platform <p> --verify --json` | **Read-only.** Checks whether stored credentials are valid -- cannot set or clear them |

`auditreach-cli` is also importable as a library, not just a CLI. Every export below comes straight from `dist/index.d.ts` in the published package.
`auditreach-cli` doubles as an importable library. Every export below comes straight from `dist/index.d.ts` in the published package.

@@ -258,2 +258,3 @@ ```ts

executeSearch,
SearchCommandError,
checkAuthStatus,

@@ -308,2 +309,3 @@ executeVerifyLog,

- `executeSearch(args)`, `checkAuthStatus(platform)`, `executeVerifyLog(path?)` -- the same programmatic cores the `search` / `auth --verify` / `verify-log` CLI commands and the MCP tools both call into; none of them write to console/stdout, so they're safe to call from any host, including one sharing stdout with an MCP transport.
- `SearchCommandError` -- the error class `executeSearch` throws for an expected, user-actionable failure: no BYOK credentials stored yet for the target platform, or a Reddit search called without `--query`. Catch it specifically to distinguish "you called this wrong" from a real network/API failure.
- `buildMcpServer({ version }): McpServer` -- constructs the MCP server (from `@modelcontextprotocol/sdk`) with the `search` / `auth_status` / `verify_log` tools registered, without starting a transport -- useful for testing or embedding in a larger MCP server.

@@ -319,3 +321,3 @@ - `runMcpServerCommand({ version })` -- what `auditreach mcp` runs: builds the server and connects it over stdio. Never returns while the server is running.

| Platform | API used | Status | Known constraint |
| ----------- | ----------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ----------- | ------------------------------------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Reddit | Reddit API (OAuth2 password grant, direct REST) | Shipped | Rate limits are generally workable for real research volumes |

@@ -330,5 +332,5 @@ | YouTube | YouTube Data API v3 (`googleapis`) | Shipped | Quota-based (10,000 units/day default), generally workable |

| Platform | Default (flag omitted) | Maximum (`--max-results`) |
| -------- | ---------------------- | ------------------------- |
| Reddit | 25 | 100 |
| YouTube | 25 | 50 |
| -------- | ----------------------- | --------------------------- |
| Reddit | 25 | 100 |
| YouTube | 25 | 50 |

@@ -359,3 +361,3 @@ Values above the cap are silently clamped to it. For Reddit, `--before`/`--after` let you page through a search's result set using the real cursor Reddit's own response returns, up to Reddit's own ~1,000-item search cap (see [Success stories](#success-stories) for why cursor pagination alone can't go further than that); YouTube has no equivalent yet. Whenever the number of items returned equals the limit that was actually applied, whether that is the silent default or an explicit `--max-results` value, auditreach prints a warning to stderr telling you more results may exist and how to raise `--max-results` (up to the platform cap).

npm run typecheck # tsc --noEmit --strict
npm run test:coverage # vitest, 66 tests, 95.4% statement coverage
npm run test:coverage # vitest, 91 tests, 95.1% statement coverage

@@ -367,3 +369,3 @@ **Python (`python/`):**

pip install -e ".[dev]"
pytest # 82 tests
pytest # 95 tests

@@ -374,3 +376,3 @@ See `CONTRIBUTING.md` for the rules on adding a new platform client -- the short version: official API only, honest rate-limit disclosure, tests that mock the network boundary, never anything that reads or writes a raw credential outside `src/auth/credential-store.ts` (or `python/src/auditreach/auth/credential_store.py` on the Python side).

See `SECURITY.md` for the vulnerability disclosure policy. A pre-launch OWASP/STRIDE review found zero CRITICAL/HIGH findings and one moderate, non-directly-reachable supply-chain advisory that has since been resolved -- `npm audit` on this repo currently returns zero vulnerabilities. GitHub secret scanning and push protection are enabled on this repo.
See `SECURITY.md` for the vulnerability disclosure policy. A pre-launch OWASP/STRIDE review found zero CRITICAL/HIGH findings in auditreach's own code. As of this writing, `npm audit --audit-level=high` on a fresh install reports 3 advisories (1 moderate, 2 high) in `ip-address` and `hono` -- both pulled in transitively by the official `@modelcontextprotocol/sdk` dependency's HTTP-transport code. `auditreach mcp` only ever starts the SDK's stdio transport (`StdioServerTransport`), so that code path never runs, but the packages still ship in `node_modules` and still trip `npm audit` until upstream bumps its pinned versions. GitHub secret scanning and push protection are enabled on this repo.

@@ -377,0 +379,0 @@ ## Success stories