Linda 🛡️

An agentic security-audit harness for coding agents — Claude Code, opencode, Codex, Copilot, and anything that can run a CLI. Linda gives your agent a grounded methodology (covering established web-application, API, and network/host security techniques plus current research) and a cross-platform harness that drives best-in-class open-source scanners to audit code, dependencies, secrets, deployment/IaC, auth, APIs, and hosts — then fix, self-verify, and re-audit.

linda — Swahili for "to guard / protect."

Why

Agents give confident, wrong security advice when they reason from memory. Linda fixes that two ways:

1. Grounding. Every technique the skill uses traces to a local knowledge base (kb/) covering established web-application, API, and network/host security techniques, an ASVS-derived control set, and 2023–2026 research — queryable as a graphify knowledge graph. Cite or don't claim.
2. Real tools, not hallucinated ones. Linda builds no scanners of its own — it leverages existing best-in-class open source (semgrep, trivy, gitleaks, nuclei, ZAP, nmap), detects which are present, and normalizes their output into ranked findings. When one is missing it advises the exact install command and offers to install it with your consent (linda install-tools); only as a last resort does it fall back to a lower-fidelity built-in check — and it never pretends a scan ran that didn't.

Zero runtime dependencies. Node built-ins only. Fast, lightweight, cross-platform (macOS/Linux/Windows).

Install

npm i -g @seedexr/lindafiy      # global `linda`
# or run without installing:
npx @seedexr/lindafiy doctor

Then wire it into your agent:

linda install claude     # → ~/.claude/skills/security-audit/
linda install opencode   # → ./.opencode/skills/security-audit/
linda install codex      # → ./.codex/skills/security-audit/  (+ AGENTS.md snippet)
linda install copilot    # → ./.github/linda-security-audit/  (+ copilot-instructions snippet)

Usage

linda doctor                       # what's installed / missing + how to install each
linda install-tools                # list missing scanners + install commands (advises only)
linda install-tools --yes          # install them now (only with your consent)
linda audit [path]                 # static local audit — safe, no network
linda audit . --phases secrets,sast,deps
linda controls                     # print the ASVS control backbone
linda verify <path> --phase sast   # re-run one phase, diff vs baseline (self-verify after a fix)

# Local dev app on your machine — loopback is in-scope, no flag needed:
linda scan-web  http://localhost:3000
linda scan-api  http://127.0.0.1:8080 --spec openapi.json

# Remote/live targets — only against systems you are authorized to test:
linda scan-web  https://app.example.com --authorized
linda scan-api  https://api.example.com --authorized --spec openapi.json
linda scan-host host.example.com --authorized --intensity safe

Reports are written to <path>/.linda/ (report.md + findings.json). Add --json for machine output.

Local & pre-production development (the everyday workflow)

Linda is built for shift-left use — auditing code on your machine long before it reaches production. This is the default and it is completely safe:

• linda audit [path] scans any local codebase — a repo you're building, a checkout that isn't deployed anywhere, a monorepo package — entirely offline. It never makes a network request, never talks to prod, and writes only to <path>/.linda/. Run it on a feature branch, in a pre-commit hook, or in CI on every PR.
• Fix loop: the agent proposes a root-cause fix, you apply it, then linda verify <path> --phase <name> re-runs just that check and diffs resolved/new/persisting — so you confirm the fix locally before anything ships.
• Locally-running app: point the active scanners at your dev server — linda scan-web http://localhost:3000. Loopback targets (localhost, 127.0.0.1, ::1) are treated as in-scope automatically (it's your machine), so no --authorized flag is needed. Only remote hosts require that assertion.

Nothing here needs a deployed system, a prod URL, or credentials. Point Linda at a folder or your local dev server and go.

Prod simulation locally (linda simulate)

Test your app against a production-like HTTPS environment on your own machine before it ships — a TLS-terminating reverse proxy in front of your dev app, with a generated cert and prod-like security headers:

# Start your app first (e.g. on :3000), then:
linda simulate up --upstream localhost:3000        # → https://localhost:8443
linda scan-web https://localhost:8443              # scan the prod-like surface (loopback: no flag)
linda simulate down                                # tear it down

Engine is auto-selected from what you have:

• Docker (recommended) → nginx + self-signed TLS, closest to a real prod edge.
• Caddy (no Docker needed) → single binary, automatic HTTPS, runs on the host.
• Neither? Linda advises how to install either (and can auto-install Caddy with consent: linda simulate up --yes), or points you to manual options (mkcert, native nginx+openssl, your framework's HTTPS dev mode).

Self-signed/local cert → pass your scanner's insecure flag (e.g. nuclei/ZAP accept -k).

Every fix ships with tests

When Linda (or your agent) fixes a finding, it doesn't just patch — it adds unit + integration + regression tests for the fix, using your project's test framework:

• unit — the fixed function rejects/escapes the exploit input;
• integration — the endpoint/flow returns safe behavior (payload → 400, IDOR → 403);
• regression — a permanent test named for the vulnerability, so it can never silently reopen.

Phases

phase	what it finds	preferred tool	fallback
recon	stack, frameworks, deploy files, trust boundaries	built-in	—
secrets	hardcoded credentials / keys	gitleaks	regex scan
sast	injection, XSS, unsafe sinks	semgrep (+ bandit)	skip w/ install hint
deps	vulnerable dependencies	trivy → osv-scanner	npm audit
iac	Docker/k8s/Terraform misconfig	trivy config	checkov
config	CORS *, JWT alg=none, string-SQL, eval, exec, insecure cookies, TLS-verify-off	built-in heuristics	—
dast*	web vulns	nuclei → ZAP	suggests command
api*	OWASP API Top 10	nuclei + agent playbook	suggests command
host*	open ports, services, SSH hardening	nmap	suggests command

* Active phases — need a target. Loopback/local targets run freely; remote targets require --authorized.

Ethics & authorization

The active phases (scan-web, scan-api, scan-host) and the offensive techniques in the KB are for authorized testing only: your own systems, systems you have written permission to test, CTF targets, or security research. Loopback targets on your own machine (localhost, 127.0.0.1, ::1) run freely — that's local dev. Every remote target is gated behind an explicit --authorized flag. Linda runs scanners in safe defaults and never improvises raw exploitation. Use it defensively.

How the agent uses it

The installed skill (SKILL.md) tells the agent to: run linda doctor → linda audit → read the ranked findings → confirm leads against the code → review auth/logic by hand against the KB → (if authorized) run active scans → fix at the root cause → add a regression test → linda verify → report. It never commits — you review and commit.

Development

npm test        # unit + integration + regression tests (node:test, no framework) against a vulnerable fixture

Versioning & releasing

VERSION (repo root) is the single source of truth. linda --version, package.json, and CI all read from it.

Bump the version (either works — they stay in sync):

# Option A — edit the VERSION file, then propagate:
echo "0.2.0" > VERSION && npm run sync-version

# Option B — npm idiom (the `version` hook writes VERSION back automatically):
npm version 0.2.0

npm version 0.1.0 errors with "Version not changed" — that's npm refusing a no-op bump because the version is already 0.1.0. You don't need it for the first release.

Publish 0.1.0 (already the current version — no bump needed):

• CI / OIDC (recommended): push to github.com/SeedeXR/lindafiy, complete the one-time Trusted Publisher setup on npmjs.com (repo + .github/workflows/publish.yml), then create a GitHub Release tagged v0.1.0. The publish workflow verifies the tag matches VERSION, runs tests, and publishes with provenance — no token.
• Local one-off: npm login then npm publish --access public. (prepublishOnly runs the version check + tests first. Omit --provenance locally — provenance requires the CI OIDC identity.)

License

MIT © Seede Group Company Limited (trading as Seede XR). See LICENSE.

Not affiliated with OWASP, ProjectDiscovery (nuclei), or Zaproxy (ZAP); Linda orchestrates those tools when you have them installed.