ubon
Version:
Security scanner for AI-generated apps (Cursor, Lovable, Windsurf, v0). Catches hardcoded secrets, prompt injection, hallucinated imports, Server Actions / Edge runtime mistakes, and the vibe-coded vulnerabilities traditional linters miss.
201 lines (159 loc) âĒ 8.43 kB
Markdown
# ðŠ· Ubon
<p align="center">
<img src="branding/Ubon.png" alt="Ubon â Peace of mind for AI-generated apps" width="100%" />
</p>
> **Security scanner for AI-generated apps.**
> Catches the bugs Cursor, Lovable, Windsurf, v0, and Claude routinely
> ship: hardcoded LLM keys, prompt-injection sinks, leaked Server
> Actions, hallucinated imports, missing auth on streaming endpoints,
> and the other "looks fine to a linter" issues that traditional tools
> miss.
[](https://badge.fury.io/js/ubon)
[](https://npmjs.com/package/ubon)
[](https://opensource.org/licenses/MIT)
[](#requirements)
## Quick start
```bash
# One-shot, no install
npx ubon@latest check
# Or install globally
npm install -g ubon
ubon check
```
```bash
ubon check # fast static scan, exit 1 on errors
ubon scan --interactive # walk through findings one by one
ubon check --json # deterministic JSON for agents/CI
ubon rules list --json # machine-readable rule catalog
ubon check --sarif out.sarif # SARIF 2.1.0 for GitHub code scanning
ubon mcp # serve as an MCP tool to your AI assistant
ubon doctor # check environment and optional deps
```
## Why Ubon?
Modern AI coding assistants are great at producing **code that runs**.
They are routinely careless about code that's **safe to deploy**:
- Hardcoded LLM API keys in client bundles
- Server Actions with no auth check
- Streaming routes with no rate limit
- MCP server configs with literal secrets
- `import.meta.env.PUBLIC_*` reading server-only values
- `'use client'` files importing from `actions/`
- Edge runtime routes calling Node-only APIs
- Hallucinated imports that pass the type checker because the package never gets installed
Ubon's job is to catch those, fast, with high confidence and `file:line`
context â and to expose them to the agent itself via JSON / NDJSON / MCP
so the AI can fix what it broke.
## v3.2.0 â what's new
v3.2.0 is an additive release for agentic development workflows: installable
guardrails, richer machine-readable output, and a validation harness that
proves Ubon catches planted AI-era bugs before a release ships.
- **Agent harness installer**: `ubon agent install --all --write` can generate
Cursor, Claude Code, Codex, pre-commit, GitHub Actions, and `.gitignore`
harness files from one dry-run-first workflow.
- **Expanded Cursor hooks**: templates now cover file edits, shell commands,
MCP calls, prompt submission, stop gates, and pre-compaction context.
- **Agent-specific rules** (`CC009`â`CC011`): catches unknown Cursor hook
events, broad agent autonomy, and dangerous reusable commands / skills.
- **Agent-ready CLI**: `ubon changed`, `ubon verify`, `ubon review`,
`ubon rules list --json`, and presets for `agent`, `ci`, `release`, and
`local` workflows.
- **MCP upgrade**: tools for changed-file scans, `baseSha`, verification,
status, rule catalog access, and fix planning.
- **Repair context**: JSON / MCP output can include source context so agents
have enough local evidence to patch findings.
- **Validation harness**: fixture benchmarks, CLI/MCP contract tests,
deterministic fix/rescan checks, dogfood, and package dry-run verification
are wired into `npm run verify:release`.
- **Release discipline**: `npm run dogfood` scans Ubon itself and must pass
with 0 unsuppressed critical findings before publish.
For the original v3 breaking changes (Node 20+, removed Python / Rails / Vue
profiles), see [MIGRATION-v3.md](MIGRATION-v3.md).
## How it compares
| Capability | Ubon | ESLint | npm audit | Lovable scanner |
| ------------------------------------- | ---- | ------------- | --------- | --------------- |
| LLM / vector-DB hardcoded secrets | â
| â | â | â ïļ Partial |
| Prompt-injection sinks | â
| â | â | â |
| Server Actions / Edge runtime checks | â
| â | â | â |
| Supabase RLS validation | â
| â | â | â ïļ Existence |
| Insecure cookies / CORS / redirects | â
| â | â | â |
| Client env-var leaks (Next/Vite) | â
| â | â | â |
| Accessibility basics | â
| â ïļ Plugins | â | â |
| Dependency advisories (OSV) | â
| â | â
| â |
| MCP server for AI agents | â
| â | â | â |
| Code style / formatting | â | â
| â | â |
**Use them together.** ESLint covers code style; npm audit covers CVEs
in your dependency tree; Ubon covers the gap that AI assistants
regularly leave behind.
## Cursor integration
```bash
ubon agent install --cursor --write # writes Cursor hooks + rules
```
Then point Cursor at the MCP server:
```jsonc
// ~/.cursor/mcp.json
{
"mcpServers": {
"ubon": { "command": "npx", "args": ["-y", "ubon@latest", "mcp"] }
}
}
```
Full Cursor + Lovable + comparison details in
[docs/INTEGRATIONS.md](docs/INTEGRATIONS.md).
## What Ubon catches
The demo fixture in [`examples/ai-harness-demo`](examples/ai-harness-demo)
contains the kinds of issues AI agents often leave behind: an LLM key in
source, server-side fetch to a user-controlled URL, a misspelled Cursor hook,
and a reusable agent command that pipes network output into a shell.
```bash
ubon check -d examples/ai-harness-demo --preset local
```
The expected rule IDs are checked by the test suite so the demo stays honest.
## Configuration
```bash
ubon init # writes ubon.config.json
ubon check --update-baseline # accept current findings as baseline
ubon check --baseline .ubon-baseline.json --focus-new --fail-on error
```
```jsonc
// ubon.config.json
{
"profile": "next",
"minConfidence": 0.85,
"failOn": "error",
"disabledRules": ["VIBE003"],
"exclude": ["legacy/**"]
}
```
For the JS variant (executes user code), pass `--allow-config-js` or
set `UBON_ALLOW_CONFIG_JS=1`.
## Documentation
- [docs/CLI.md](docs/CLI.md) â every command and flag
- [docs/START-HERE.md](docs/START-HERE.md) â two-minute setup and daily commands
- [docs/AGENT-HARNESS.md](docs/AGENT-HARNESS.md) â Cursor / Claude Code / Codex / MCP / hooks
- [docs/AGENT-SEMANTICS.md](docs/AGENT-SEMANTICS.md) â how Ubon models agent events, rules, and gates
- [docs/PROGRAMMATIC.md](docs/PROGRAMMATIC.md) â Node API, JSON/NDJSON, and MCP contracts
- [docs/RULES.md](docs/RULES.md) â full rule glossary
- [docs/CONFIG.md](docs/CONFIG.md) â config file schema
- [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md) â Cursor / Lovable / comparison
- [docs/MCP.md](docs/MCP.md) â Model Context Protocol server
- [docs/ADVANCED.md](docs/ADVANCED.md) â profiles, suppressions, baselines, output schemas, release policy
- [docs/RELEASE.md](docs/RELEASE.md) â release verification and publish checklist
- [docs/VALIDATION.md](docs/VALIDATION.md) â dogfood, fixtures, contracts, and repair loops
- [MIGRATION-v3.md](MIGRATION-v3.md) â upgrading from v2.x
- [CHANGELOG.md](CHANGELOG.md) â release history
## Requirements
- Node.js **20 or newer** (v3 dropped Node 16/18)
- Git (for `--git-changed-since` and the `git-history` scanner)
- Optional: `@modelcontextprotocol/sdk` for `ubon mcp` â installed
automatically as an `optionalDependency` of `ubon`. If your install
flags skipped it, see [`docs/MCP.md`](docs/MCP.md#install).
Run `ubon doctor` to verify.
## About
I'm [Luisfer Romero Calero](https://lfrc.me). I built Ubon because the
gap between "AI shipped this" and "this is safe to deploy" keeps
widening. The tool's name comes from the lotus (āļāļļāļāļĨ) in Thai â
clarity in the middle of vibe-coded chaos.
If Ubon helps you ship safer apps, the highest praise is to wire it
into your CI and your AI assistant â and tell me what it caught.
## License
MIT â see [LICENSE](LICENSE).