@hybridlabor-api/aos 4.6.5 → 4.7.0

package/skills/global_config/archify/scripts/generate-brand-marks.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as simpleIcons from 'simple-icons';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(here, '..');
+const catalogPath = path.join(root, 'brand-marks', 'catalog.json');
+const outputPath = path.join(root, 'renderers', 'shared', 'generated-brand-marks.mjs');
+const catalog = JSON.parse(fs.readFileSync(catalogPath, 'utf8'));
+const simpleIconsVersion = JSON.parse(fs.readFileSync(
+  path.join(root, 'node_modules', 'simple-icons', 'package.json'),
+  'utf8',
+)).version;
+const simpleBySlug = new Map(Object.values(simpleIcons)
+  .filter((icon) => icon && typeof icon === 'object' && icon.slug && icon.path)
+  .map((icon) => [icon.slug, icon]));
+
+function normalizedList(value) {
+  return [...new Set((Array.isArray(value) ? value : [])
+    .map((item) => String(item).trim())
+    .filter(Boolean))];
+}
+
+function lookupForms(value) {
+  const raw = String(value ?? '').trim().toLocaleLowerCase('en-US');
+  if (!raw) return [];
+  return [...new Set([
+    raw,
+    raw.replace(/[\s_]+/g, '-'),
+    raw.replace(/[\s_.-]+/g, ''),
+  ])];
+}
+
+function fail(message) {
+  console.error(`brand catalog: ${message}`);
+  process.exit(1);
+}
+
+if (catalog.schemaVersion !== 1 || !Array.isArray(catalog.marks) || catalog.marks.length === 0) {
+  fail('catalog.json must contain a non-empty schemaVersion 1 marks array');
+}
+
+const ids = new Set();
+const lookupKeys = new Map();
+const domains = new Map();
+const generated = catalog.marks.map((entry, index) => {
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(entry.id || '')) fail(`marks[${index}] has an invalid id`);
+  if (ids.has(entry.id)) fail(`duplicate id ${entry.id}`);
+  ids.add(entry.id);
+
+  const aliases = normalizedList(entry.aliases);
+  const entryDomains = normalizedList(entry.domains).map((domain) => domain.toLowerCase());
+  for (const key of [entry.id, ...aliases]) {
+    for (const form of lookupForms(key)) {
+      if (lookupKeys.has(form) && lookupKeys.get(form) !== entry.id) {
+        fail(`lookup key ${JSON.stringify(key)} is shared by ${lookupKeys.get(form)} and ${entry.id}`);
+      }
+      lookupKeys.set(form, entry.id);
+    }
+  }
+  for (const domain of entryDomains) {
+    if (domains.has(domain) && domains.get(domain) !== entry.id) {
+      fail(`domain ${domain} is shared by ${domains.get(domain)} and ${entry.id}`);
+    }
+    domains.set(domain, entry.id);
+  }
+
+  let mark;
+  if (entry.simpleIcon) {
+    const icon = simpleBySlug.get(entry.simpleIcon);
+    if (!icon) fail(`${entry.id} references missing Simple Icons slug ${entry.simpleIcon}`);
+    mark = {
+      id: entry.id,
+      title: entry.title || icon.title,
+      category: entry.category,
+      aliases,
+      domains: entryDomains,
+      viewBox: 24,
+      hex: icon.hex,
+      path: icon.path,
+      provenance: {
+        provider: 'Simple Icons',
+        providerVersion: simpleIconsVersion,
+        source: icon.source,
+        ...(icon.guidelines ? { guidelines: icon.guidelines } : {}),
+        ...(icon.license ? { license: icon.license } : {}),
+      },
+    };
+  } else if (entry.custom) {
+    const custom = entry.custom;
+    if (!entry.title || !custom.path || !custom.source || !/^[0-9A-F]{6}$/i.test(custom.hex || '')) {
+      fail(`${entry.id} custom mark requires title, path, source, and six-digit hex`);
+    }
+    mark = {
+      id: entry.id,
+      title: entry.title,
+      category: entry.category,
+      aliases,
+      domains: entryDomains,
+      viewBox: custom.viewBox || 24,
+      hex: custom.hex.toUpperCase(),
+      path: custom.path,
+      provenance: {
+        provider: 'Official brand asset',
+        source: custom.source,
+        ...(custom.guidelines ? { guidelines: custom.guidelines } : {}),
+      },
+    };
+  } else {
+    fail(`${entry.id} must provide simpleIcon or custom`);
+  }
+  if (!mark.category || !mark.title) fail(`${entry.id} is missing category or title`);
+  for (const form of lookupForms(mark.title)) {
+    if (lookupKeys.has(form) && lookupKeys.get(form) !== entry.id) {
+      fail(`title ${JSON.stringify(mark.title)} is shared by ${lookupKeys.get(form)} and ${entry.id}`);
+    }
+    lookupKeys.set(form, entry.id);
+  }
+  return mark;
+}).sort((left, right) => left.id.localeCompare(right.id));
+
+const banner = `// Generated by scripts/generate-brand-marks.mjs from brand-marks/catalog.json.\n// Simple Icons ${simpleIconsVersion}. Do not edit by hand.\n`;
+const source = `${banner}export const BRAND_MARKS = Object.freeze(${JSON.stringify(generated, null, 2)});\n`;
+
+if (process.argv.includes('--check')) {
+  const current = fs.existsSync(outputPath)
+    ? fs.readFileSync(outputPath, 'utf8').replace(/\r\n?/g, '\n')
+    : '';
+  if (current !== source) {
+    console.error('generated brand marks are stale — run npm run generate:brand-marks');
+    process.exit(1);
+  }
+} else {
+  const temporary = `${outputPath}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, source);
+  fs.renameSync(temporary, outputPath);
+  console.log(`generated ${path.relative(root, outputPath)} (${generated.length} marks)`);
+}

package/skills/global_config/archify/scripts/generate-validators.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Ajv2020 from 'ajv/dist/2020.js';
+import standaloneCode from 'ajv/dist/standalone/index.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(__dirname, '..');
+const schemasDir = path.join(root, 'schemas');
+const output = path.join(root, 'renderers/shared/generated-validators.mjs');
+const diagramTypes = ['workflow', 'sequence', 'dataflow', 'lifecycle', 'architecture'];
+
+const ajv = new Ajv2020({
+  allErrors: true,
+  strict: true,
+  code: { source: true, esm: true },
+});
+ajv.addSchema(JSON.parse(fs.readFileSync(path.join(schemasDir, 'common.schema.json'), 'utf8')));
+
+const schemaIds = {};
+for (const type of diagramTypes) {
+  const schema = JSON.parse(fs.readFileSync(path.join(schemasDir, `${type}.schema.json`), 'utf8'));
+  ajv.addSchema(schema);
+  schemaIds[type] = schema.$id;
+}
+
+const banner = '// Generated by scripts/generate-validators.mjs. Do not edit by hand.\n';
+const ajvUcs2Import = 'require("ajv/dist/runtime/ucs2length").default';
+const inlineUcs2Length = `function ucs2length(str) {
+  const len = str.length;
+  let length = 0;
+  let pos = 0;
+  while (pos < len) {
+    length += 1;
+    const value = str.charCodeAt(pos++);
+    if (value >= 0xd800 && value <= 0xdbff && pos < len
+      && (str.charCodeAt(pos) & 0xfc00) === 0xdc00) pos += 1;
+  }
+  return length;
+}`;
+let validatorCode = standaloneCode(ajv, schemaIds);
+if (!validatorCode.includes(ajvUcs2Import)) {
+  throw new Error('AJV standalone output no longer contains the expected ucs2length helper');
+}
+validatorCode = validatorCode.replaceAll(ajvUcs2Import, inlineUcs2Length);
+if (validatorCode.includes('require(')) {
+  throw new Error('AJV standalone output contains an unexpected runtime dependency');
+}
+const generated = `${banner}${validatorCode}\n`;
+
+if (process.argv.includes('--check')) {
+  const current = fs.existsSync(output)
+    ? fs.readFileSync(output, 'utf8').replace(/\r\n?/g, '\n')
+    : '';
+  if (current !== generated) {
+    console.error('generated validators are stale — run npm run generate:validators');
+    process.exit(1);
+  }
+} else {
+  const temporary = `${output}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, generated);
+  fs.renameSync(temporary, output);
+  console.log(`generated ${path.relative(root, output)}`);
+}

package/skills/global_config/archify/scripts/render-examples.mjs

@@ -0,0 +1,26 @@
+// Re-render every bundled example from its JSON IR. Installed skills keep HTML
+// beside the JSON examples; the development script passes the golden directory.
+
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const skillRoot = path.resolve(__dirname, '..');
+const outputRoot = path.resolve(process.argv[2] || path.join(skillRoot, 'examples'));
+
+const TARGETS = [
+  ['workflow', 'agent-tool-call.workflow.json', 'workflow-agent-tool-call-rendered.html'],
+  ['sequence', 'cache-miss-request.sequence.json', 'sequence-cache-miss-request.html'],
+  ['dataflow', 'product-analytics.dataflow.json', 'dataflow-product-analytics.html'],
+  ['lifecycle', 'agent-run.lifecycle.json', 'lifecycle-agent-run.html'],
+  ['architecture', 'web-app.architecture.json', 'web-app-rendered.html'],
+];
+
+for (const [mode, input, output] of TARGETS) {
+  execFileSync(process.execPath, [
+    path.join(skillRoot, `renderers/${mode}/render-${mode}.mjs`),
+    path.join(skillRoot, 'examples', input),
+    path.join(outputRoot, output),
+  ], { stdio: 'inherit' });
+}

package/skills/global_config/archify/skill-release.json

@@ -0,0 +1,10 @@
+{
+  "schemaVersion": 1,
+  "skillId": "archify",
+  "channel": "development",
+  "version": "2.17.0-dev.1",
+  "source": {
+    "repository": "https://github.com/tt-a1i/archify"
+  },
+  "updateManifestUrl": "https://tt-a1i.github.io/archify/skill-updates/archify/stable.json"
+}

package/skills/global_config/bdb-security-audit/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: bdb-security-audit
+description: Comprehensive security auditing, diff analysis, defensive checklists, and vulnerability testing.
+category: engineering-method
+user-invocable: true
+---
+
+# BDB Security Audit
+
+Defensive security auditing for BDB projects. Use before commits, during PR review,
+inside the Shipping quality gate, or whenever a codebase needs a structured security
+pass. This skill is **defensive only**: it verifies, hardens, and reports. It never
+produces attack tooling, exploit payloads, or offensive reconnaissance.
+
+## The Three Pillars
+
+| Pillar | What it is | When it runs |
+|---|---|---|
+| **Skylos** | Diff and AST-level security analyzer for code changes. Catches dangerous call patterns, hardcoded credentials, and dead code that carries secrets — on staged files and PR diffs, before they land. | Pre-commit, PR review, Shipping gate |
+| **Claude-Red Checklists** | Structured defensive audit checklists derived from red-team knowledge, inverted into verification questions. Covers OWASP Top 10, AuthN/AuthZ, injection classes, SSRF, LLM/agent security, and secret leakage. | Deep audits, new-feature review, release prep |
+| **Xalgorix Bridge** | Decoupled connection to the `xalgorix` automated security suite. Discovered at runtime via `$PATH` or `XALGORIX_URL` — never hardcoded. Runs broader automated scans and returns findings. | Scheduled scans, pre-release sweeps, CI |
+
+The pillars are independent. A machine may have none, one, or all three; every
+workflow below degrades gracefully and must report "could not check" rather than
+"checked, fine" when a tool is absent.
+
+## When to Use
+
+- "Audit this before I push" — run Skylos on the diff, then the relevant checklists.
+- "Security review this PR" — `skylos diff` against the base branch, triage findings.
+- Shipping gate step — Skylos must pass (or every finding must be dispositioned) before a release.
+- "Is this endpoint/agent/tool safe?" — pull the matching section from `references/audit-checklists.md`.
+- Periodic automated sweep — Xalgorix Bridge, if the suite is reachable.
+
+## Workflow
+
+### 1. Diff pass (always first, always cheap)
+
+```sh
+# Staged / uncommitted changes
+skylos diff
+
+# Whole tree, if no baseline exists
+skylos scan .
+```
+
+Verify the binary exists first — `command -v skylos` — and check `skylos --help`
+for the flags your installed version supports. If skylos is absent, record
+**"could not check"** and continue; do not silently treat the step as passed.
+
+### 2. Checklist pass (targeted, human-driven)
+
+Open `references/audit-checklists.md` and work only the sections the change
+touches: touched auth code → Authentication & Session Management; new endpoint →
+Input Validation + Infrastructure; new agent/tool surface → LLM & Agent Security.
+Every item is phrased as a verification question. Mark each **pass / fail / not
+applicable** — an unmarked item is not a pass.
+
+### 3. Automated sweep (optional, decoupled)
+
+```sh
+# Discover the suite — never assume, never hardcode
+command -v xalgorix || echo "not on PATH"
+echo "${XALGORIX_URL:-not configured}"
+```
+
+If neither is present, skip and report. If present, run the scan per
+`references/xalgorix-bridge.md` and forward findings to Reviewer/Shipping.
+
+### 4. Report
+
+Consolidate into one summary for Reviewer or Shipping:
+
+- Per finding: file, line, severity, checklist or scanner origin, disposition (fix now / ticket / accepted risk).
+- Per check: `pass`, `fail`, or `could not check` — never leave a check unreported.
+- A gate verdict only from evidence: a passing report with two "could not check" rows is **not** a green gate.
+
+## Commands Quick Reference
+
+```sh
+command -v skylos            # pillar 1 present?
+skylos diff                  # security scan of staged/changed code
+skylos scan .                # full-tree scan
+skylos --help                # confirm flags for your installed version
+
+command -v xalgorix          # pillar 3 on PATH?
+echo "$XALGORIX_URL"         # pillar 3 via remote endpoint?
+```
+
+## Guardrails
+
+1. **Defensive posture only.** Findings describe what is wrong and how to fix it.
+   Never write or store exploit payloads, working attack strings, or recon steps —
+   not even in reports, tickets, or memory.
+2. **No hardcoded paths.** Tools are discovered via `$PATH` or environment
+   variables (`XALGORIX_URL`). Skills, agents, and configs never contain absolute
+   machine paths.
+3. **No secret leakage.** Audit outputs must redact credentials, tokens, and keys
+   found during scanning. Name the file and line, never the value.
+4. **Honest gates.** "Could not check" is a distinct, reported state. Silent
+   degradation to "pass" is the defect class this skill exists to prevent.
+5. **English only, minimal scope.** Reports state findings and fixes; they do not
+   lecture, and they do not expand scope beyond the diff or audit target.
+
+## References
+
+- [references/audit-checklists.md](references/audit-checklists.md) — the full defensive checklist set.
+- [references/skylos-guide.md](references/skylos-guide.md) — installing, running, and interpreting Skylos; Shipping gate wiring.
+- [references/xalgorix-bridge.md](references/xalgorix-bridge.md) — runtime discovery, decoupled configuration, scan reporting.

package/skills/global_config/bdb-security-audit/references/audit-checklists.md

@@ -0,0 +1,172 @@
+# Defensive Audit Checklists
+
+Derived from the Claude-Red body of knowledge, inverted into verification questions.
+Every item is something an auditor **checks for presence and correctness** in the
+defended codebase. Work only the sections the change or system under audit touches.
+Mark each item `pass`, `fail`, or `n/a`; an unmarked item is not a pass, and a
+section you could not verify is reported as **could not check**.
+
+Severity guidance when a check fails:
+
+| Severity | Meaning |
+|---|---|
+| `blocking` | Exploitable by any untrusted party with the exposure the system already has. Fix before ship. |
+| `high` | Exploitable with modest preconditions (a valid low-privilege account, a known config). Fix or ticket before ship. |
+| `medium` | Requires special conditions or adds defense-in-depth gaps. Ticket. |
+| `low` | Hygiene and hardening. Backlog. |
+
+---
+
+## 1. Authentication & Session Management
+
+- [ ] Passwords are hashed with a dedicated password hash function (bcrypt, scrypt, or argon2 family) — never fast general-purpose hashes, never reversible encoding.
+- [ ] Salt is unique per credential and generated by the hashing library itself.
+- [ ] Password/secret comparison uses constant-time comparison functions, not `==`.
+- [ ] Login, password reset, and MFA endpoints are rate-limited per account and per source, with exponential backoff or lockout.
+- [ ] Authentication error messages do not reveal whether the account exists ("invalid credentials", not "unknown user").
+- [ ] Session identifiers are regenerated on privilege change (login, password change, role elevation).
+- [ ] Session cookies carry `Secure`, `HttpOnly`, and an appropriate `SameSite` attribute.
+- [ ] Session lifetime and idle timeout are explicitly configured — no infinite sessions.
+- [ ] Server-side session invalidation exists: logout actually destroys the session server-side, and "log out everywhere" is possible.
+- [ ] Password reset tokens are single-use, short-lived, and invalidated on use or on new request.
+- [ ] MFA, where present, is enforced server-side — client-side toggles cannot bypass it.
+- [ ] JWTs (if used): algorithm is pinned server-side; signature, issuer, audience, and expiry are all verified; tokens are rejected after logout via a denylist or short lifetime.
+- [ ] Service-to-service authentication uses scoped credentials (mTLS, signed tokens), not shared long-lived keys in config.
+
+## 2. Authorization & Access Control (IDOR, BOLA)
+
+- [ ] Every server-side handler performs its own authorization check — the client, frontend route guard, or API gateway is never the only gate.
+- [ ] Object access resolves ownership from the **server-side session/identity**, never from a client-supplied user or account identifier alone.
+- [ ] Sequential or guessable object identifiers (numeric IDs, slugs) are backed by an ownership/permission check, so direct object references cannot be swapped.
+- [ ] Default authorization state is **deny**; new endpoints and new object types start inaccessible and are opened deliberately.
+- [ ] Role/permission checks are centralized (one policy layer, middleware, or decorator) rather than re-implemented per handler.
+- [ ] Privilege escalation paths checked: a lower-privileged role cannot invoke operations that only a higher role should reach, including via batch/bulk endpoints.
+- [ ] Tenant isolation verified: every query that reads or writes multi-tenant data filters by tenant, including exports, search, and background jobs.
+- [ ] Admin and internal-only endpoints are not reachable through alternate routes (old API versions, debug routers, secondary ports).
+- [ ] File/record deletion and export operations re-check authorization at execution time, not only at link-rendering time.
+- [ ] API responses return only fields the caller is entitled to — no over-fetching of other users' or internal fields.
+
+## 3. Input Validation & Injection
+
+### General
+
+- [ ] All external input (query, body, headers, path segments, files, webhooks, message queues) is validated against an explicit schema at the trust boundary.
+- [ ] Validation is allow-list shaped (type, length, range, format, enumeration) rather than deny-list filtering.
+- [ ] Canonicalization happens before validation for anything that becomes a path, URL, or identifier.
+
+### SQL injection
+
+- [ ] Every query uses parameterized statements or a query builder/ORM binding — no string concatenation or f-string/format interpolation of user input into SQL, in **any** file, including "harmless" admin scripts.
+- [ ] Dynamic ordering/filtering (sort column, filter name) maps through a fixed allow-list of column/field names, never through raw input.
+- [ ] Stored procedures and raw-SQL escape hatches accept parameters, not concatenated fragments.
+- [ ] Database accounts run with least privilege (no DDL, no cross-database access unless required).
+
+### Command injection
+
+- [ ] Shell invocation is avoided where a library/API call exists; when a subprocess is unavoidable, arguments are passed as an argument array — never through a single shell-parsed string.
+- [ ] User input never reaches a shell interpreter, template engine `eval`, code `eval`, or dynamic deserialization of executable formats.
+- [ ] Working directories and environment for spawned processes are pinned; inherited secrets are pruned from child-process environments.
+
+### Server-Side Request Forgery (SSRF)
+
+- [ ] Every outbound request built from user-supplied URLs validates scheme (https only, unless there is a documented exception) and resolves the host **before** connecting.
+- [ ] Resolved addresses are checked against a deny-list: loopback, link-local, private ranges, and cloud metadata endpoints are blocked, with re-validation after every DNS resolution (DNS-rebinding defense).
+- [ ] Redirects are followed only with re-validation of each hop, or not followed at all.
+- [ ] Webhook and fetch-by-URL features apply the same outbound rules as direct user requests.
+- [ ] Outbound requests run with credentials stripped — internal service tokens are never attached to requests whose target came from user input.
+
+### Path traversal
+
+- [ ] File paths built from user input are resolved and verified to remain inside the intended base directory (`realpath` + prefix check) — including archive members on extraction (zip-slip defense).
+- [ ] Upload filenames are sanitized or replaced entirely (server-generated names); extension allow-lists are enforced, and uploads are stored outside any executable/web-served path.
+- [ ] Download/export endpoints serve by internal identifier, never by client-supplied filesystem path.
+- [ ] Symlink following is disabled or checked where the process writes into shared directories.
+
+### Output encoding (companion to all of the above)
+
+- [ ] Context-appropriate output encoding for HTML, attribute, JavaScript, URL, and CSS contexts — templating auto-escaping is on and not bypassed with raw/mark-safe constructs on user data.
+- [ ] File download responses set a safe `Content-Type` and `Content-Disposition`; user-supplied data is never reflected into response headers unencoded.
+
+## 4. LLM & Agent Security
+
+Defends AI features (chat, copilots, autonomous agents, tool-using assistants) in the audited system.
+
+### Prompt injection (direct)
+
+- [ ] System instructions are separated from user content at the API level (dedicated system role/field), and user text is never concatenated into the system prompt.
+- [ ] The model is not relied upon as the sole enforcement point: security decisions (authorization, data access, payments) are made in code, not by model output.
+- [ ] Instructions that the model must treat as untrusted data are explicitly framed as such in the prompt design.
+- [ ] Outputs that will be parsed (JSON, SQL, commands) come from structured/constrained generation or are schema-validated before use — free-text model output is never executed or interpolated into queries.
+
+### Indirect injection
+
+- [ ] Content fetched by the agent (web pages, documents, emails, tickets, repository files) is treated as untrusted input: it is quoted/delimited in prompts, never followed as instructions.
+- [ ] Retrieved content is sanitized or summarized through a defensive pass before it can influence tool calls.
+- [ ] Sources are labeled in context so the model (and reviewers of transcripts) can tell tool output from user intent.
+- [ ] Agent browsing/fetch features enforce the same SSRF and URL allow-list rules as the rest of the system.
+
+### Tool abuse
+
+- [ ] Every tool exposed to the model declares a minimal scope (read-only vs write, which resources, which actions) and enforces it server-side.
+- [ ] Destructive tools (delete, deploy, send, pay) require a confirmation step or policy check outside the model — model output alone can never trigger them.
+- [ ] Tool arguments are validated with the same rigor as public API input: the model is one more untrusted client.
+- [ ] Tool execution runs with least-privilege credentials, scoped per tool, never the operator's full identity.
+- [ ] Loops are bounded: maximum iterations, maximum spend, maximum side effects per run; runaway agents halt safely.
+
+### Insecure output handling
+
+- [ ] Model output rendered in a browser is HTML-encoded like any other untrusted string (stored prompt injection → XSS is the same defect class).
+- [ ] Model output used in code generation or config is reviewed/linted before execution; nothing is `eval`-ed.
+- [ ] Generated SQL/commands are executed through the same parameterized/argument-array paths as above.
+- [ ] Model transcripts and tool logs are stored with the same sensitivity rules as user data, and secrets reaching a transcript are redacted.
+
+## 5. Secret Management & Sensitive Data Exposure
+
+- [ ] No credentials, API keys, tokens, or connection strings in source, fixtures, seeds, tests, docs, or comments — scanners (Skylos and the platform secret scanner) run as the gate, and any finding is rotated, not just deleted (deletion does not un-leak git history).
+- [ ] Secrets are provided at runtime via a secret manager or environment injection; `.env` files are gitignored, and only `.env.example` with placeholder values is committed.
+- [ ] Secret values are never logged: log statements, error messages, and exception reports are audited for credential/PII leakage; verbose/debug logging cannot be enabled with secrets in scope in production.
+- [ ] Different environments use different credentials; production secrets are not reachable from staging/dev code paths.
+- [ ] PII is inventoried and minimized: fields collected have a purpose, storage is encrypted at rest where required, and retention/expiry is configured.
+- [ ] Sensitive data in transit uses TLS everywhere, including internal service-to-service traffic.
+- [ ] Client-visible payloads (API responses, error pages, source maps in production, bundled JS) do not contain internal identifiers, secrets, or debug data.
+- [ ] Backups and exports containing sensitive data are encrypted and access-controlled like the primary store.
+- [ ] Secret rotation is documented and tested: rotation does not require code changes or downtime, and old values are revoked after rotation.
+- [ ] Dead code, commented-out blocks, and unused config branches that once held credentials are removed — they are the highest-signal residue an attacker greps for (this is a core Skylos target).
+
+## 6. Infrastructure & API Security
+
+### CORS
+
+- [ ] CORS allow-list is explicit per origin — no wildcard origins on authenticated endpoints, no reflecting arbitrary `Origin` headers back with credentials allowed.
+- [ ] Credentials-bearing cross-origin responses restrict `Access-Control-Allow-Origin` to enumerated trusted origins only.
+- [ ] Preflight handling and allowed methods/headers are minimal — only what the frontend actually uses.
+
+### Rate limiting & abuse controls
+
+- [ ] Rate limits exist on all public endpoints, with tighter limits on auth, password reset, OTP, search, and generation endpoints (LLM endpoints also cap spend/tokens per user).
+- [ ] Limits are enforced server-side at a shared layer (gateway, middleware, or edge), not per-instance in-memory where a second instance bypasses them.
+- [ ] Request body size, upload size, pagination page size, and list depth are all capped.
+- [ ] Long-running/expensive operations are queued with concurrency limits, not executed inline per request.
+
+### Security headers & transport
+
+- [ ] `Content-Security-Policy` set with no `unsafe-inline`/`unsafe-eval` where avoidable; `X-Content-Type-Options: nosniff`; `Referrer-Policy`; `Strict-Transport-Security` on all HTTPS responses.
+- [ ] TLS versions and cipher configuration meet current guidance; certificates renew automatically.
+- [ ] Framework debug modes, stack traces, and verbose error pages are disabled in production; errors return generic messages with a correlation ID logged server-side.
+
+### API surface
+
+- [ ] API versioning exists and deprecated versions are retired on a schedule — old versions run the current authorization code, not frozen vulnerable copies.
+- [ ] Mass-assignment defense: request DTOs allow-list bindable fields; client JSON cannot set internal fields (role, tenant, price, owner).
+- [ ] Error responses do not enumerate valid resources differently from invalid ones where that difference leaks account/data existence.
+- [ ] Introspection/admin endpoints (API docs, health, metrics, actuator-style routes) are authenticated or network-restricted in production.
+- [ ] Dependencies are pinned and scanned for known vulnerabilities on a schedule and in CI; the audit notes the last scan date and result.
+
+---
+
+## Reporting Discipline
+
+1. Record per item: `pass` / `fail` / `n/a` / `could not check` — with evidence (file:line) for every claim.
+2. Never read back your own writes as evidence: the fact that a fix was written is not proof the check passes; re-verify after the fix.
+3. Failures of `blocking`/`high` items stop the gate; the report goes to Reviewer/Shipping with disposition per finding.
+4. Redact any secret values encountered — reference location, never content.

package/skills/global_config/bdb-security-audit/references/skylos-guide.md

@@ -0,0 +1,139 @@
+# Skylos Guide — Diff & AST Security Scanning
+
+Skylos is pillar 1 of the BDB Security Audit skill: a static security analyzer that
+works at the **AST level** (it parses code structure, not text) and supports
+**diff mode**, so it can gate exactly the lines a PR or staging area touches.
+Its role is a pre-commit and Shipping quality-gate check — the automated half of
+`bdb-security-audit`, before the human-driven checklists run.
+
+This guide covers installation, running, gate integration, and interpretation.
+Command surface below reflects the two core entrypoints (`skylos scan`,
+`skylos diff`); **always confirm flags against `skylos --help` for the installed
+version** — do not assume flags from this document alone.
+
+## 1. Installation
+
+Skylos ships as a Python CLI package. Install it as an isolated tool so it does
+not pollute project environments:
+
+```sh
+# Preferred: isolated tool install
+pipx install skylos
+# or
+uv tool install skylos
+
+# Verify
+command -v skylos
+skylos --help
+```
+
+If `command -v skylos` finds nothing, the pillar is **absent**: report
+"could not check" for the scan step. Never fake a pass, and never hardcode an
+install location into scripts or skills — install via the standard tool manager
+so it lands on `$PATH`.
+
+## 2. Running
+
+### Diff mode — PRs and staged changes (primary use)
+
+Diff mode scans only what changed, which keeps the signal high and the runtime low:
+
+```sh
+skylos diff                 # staged / uncommitted changes vs the baseline
+```
+
+Typical review flow:
+
+```sh
+git checkout feature-branch
+skylos diff                 # security view of the branch's changes
+```
+
+Run it before every push and as the first step of any PR security review.
+Findings on diff mode are gate-relevant by default — the change introduced them.
+
+### Full-tree mode — audits and baselines
+
+```sh
+skylos scan .               # whole project, from the repo root
+```
+
+Use full scans for: first-time audits, release preparation, and re-scanning after
+a dependency or architecture change. Full scans surface legacy findings the diff
+never touched; triage those into tickets rather than blocking the current PR on them.
+
+### Version pinning in CI
+
+Pin the version in CI/workflows so a scanner upgrade cannot silently change gate
+behavior mid-release. Update the pin deliberately, review the new findings, then
+bump.
+
+## 3. Integration into the Shipping Quality Gate
+
+Position Skylos as a **blocking** gate step, after lint/typecheck and before the
+release decision:
+
+```text
+Build → Lint → Typecheck → [Skylos security scan] → Tests → Reviewer → Shipping
+```
+
+Gate rules:
+
+1. **Non-zero exit = gate failure.** A scanner that exits with findings must stop
+   the gate. Do not wrap the command in a way that swallows the exit code, and do
+   not `|| true` it. A discarded exit code is a swallowed failure.
+2. **Empty output on a run that claims to have run is a failure**, not a pass —
+   the same rule as delegated CLIs: verify the finding list exists and names real
+   files, never trust a bare success status.
+3. **Disposition every finding.** Each finding ends as `fixed`, `ticketed (link)`,
+   or `accepted risk (who accepted, why)`. An untriaged finding blocks the gate.
+4. **"Could not check" is reported, not skipped.** If skylos is unavailable in the
+   gate environment, the gate report lists the step as `could not check` and the
+   release decision accounts for it — it must not read as green.
+5. **Fixes re-scan.** After remediation, re-run the same scan command; the fix is
+   proven by the new scan output, not by the edit having been made.
+
+## 4. Interpreting Findings: AST Security vs Style Lints
+
+Skylos reads the AST, so its findings differ in kind from style-linter output.
+Keep the two categories separate — they have different severities and different
+dispositions:
+
+| | Style lint | AST security finding |
+|---|---|---|
+| Source | Textual/format conventions | Code structure: data flow, call patterns, definitions |
+| Examples | Naming, formatting, unused imports as a tidiness matter | Credential material in source, dangerous call patterns, dead code paths that retain secrets |
+| Default severity | Advisory | Gate-blocking until dispositioned |
+| Suppression | Fine, with a reason | Only via the scanner's explicit ignore mechanism **with an inline justification comment**; never by weakening lint config or filtering output |
+
+Interpretation rules:
+
+- **Hardcoded credential findings are always blocking.** Even test fixtures:
+  real-looking keys in tests train the habit and leak via public fixtures. Replace
+  with placeholders and rotate anything that was ever committed.
+- **Dead-code findings are security-relevant, not cosmetic.** An unused function
+  that contains a connection string or an obsolete auth path is attack surface and
+  residue; removal is the fix, suppression is not.
+- **Dangerous-call findings** (execution/serialization primitives reachable with
+  untrusted input) are validated against the checklist item that matches them —
+  see `references/audit-checklists.md` §3 and §4. The scanner says *where*;
+  the checklist decides *how bad, given the data flow*.
+- **False positives:** suppress in the code at the finding site with a reason
+  (`# skylos: ignore — <why this input is trusted>`), never globally, never by
+  post-processing the report. A global filter hides tomorrow's real finding.
+- **Findings vs the diff:** in diff mode, a finding means *this change* introduced
+  or reactivated the issue — treat it as belonging to the PR author's gate. A
+  finding that predates the branch is triaged out of the PR and ticketed.
+
+## 5. Reporting to Reviewer/Shipping
+
+The scan result enters the gate report as:
+
+```text
+Skylos: <pass | fail | could not check>  (command: skylos diff, exit: N)
+Findings:
+  - <file>:<line> — <rule/summary> — severity — disposition
+```
+
+One line per finding, every finding dispositioned, secrets redacted (name the
+file and line, never the value).