Skip to content

docs-ia.md

Latest commit

 

History

History
214 lines (152 loc) · 19.6 KB

docs-ia.md

File metadata and controls

214 lines (152 loc) · 19.6 KB
Raw

SafeDep Documentation — Information Architecture

Status: Living document · Canonical home: this file (mirrored to Notion) · Rationale & benchmarks: docs-ia-proposal.md

This is the canonical, maintained description of how the SafeDep docs are organized and how new content must be placed. When the structure changes, update this file, the Notion mirror, and the condensed copy in CLAUDE.md.

1. The structure

Seven tabs — solution tabs at the core, plus supporting tabs.

Tab Purpose Groups
Get Started What is SafeDep, vocabulary, entry points Introduction · Core Concepts
Package Security Block malicious packages at install time — on dev machines and in CI/CD — and scan any component on demand before use Install-Time Package Blocking · MDM · On-Demand Package Scanning · CI/CD Package Blocking
AI Agent Security Discover, audit, and control what AI agents access and run AI Agent Observability · AI Coding Protection
Visibility & Governance Scan repos, SBOMs, and CI/CD for supply-chain risk; deploy fleet tooling; manage policy and org-wide cloud visibility Repository Scanning · MDM · Bill of Materials · AI Visibility · CI/CD & Platform Integrations · SafeDep Cloud (nests Endpoint Hub, Policy & Risk, Authentication)
Threat Intel Consume the malicious-package feed as an API: reports and campaigns. Subscription-gated (FEATURE_THREAT_INTEL_FEED) Getting Started · Consuming the Feed · Reference
Reference Exact syntax, flags, API specs — no explanation Query & Policy · API & Automation
Community & Support Community resources, FAQ Community · Support

Implementation note: the 6-tab structure is live in docs.json (Phase 1 re-tab complete). Moving page files to solution-aligned folders is a later phase; legacy paths (vet/, cloud/, apps/, xbom/) stay grandfathered until then.

2. Governing rules

Every structural decision derives from these rules. Full rationale in docs-ia-proposal.md.

  • R1 — One primary entry point. New visitors meet a clear "What is SafeDep?" primer and capability overview, not a tool catalog.

  • R2 — Capability ladder, not persona gate. The user journey runs: individual dev → team → org-wide governance. Navigation does not pin users to a tier or imply a pricing ceiling. Features that require SafeDep Cloud are marked with a simple <Note> callout — no structural separation.

  • R3 — Organize by solution, not by tool. Tabs name the security outcome SafeDep delivers. Tools appear one level deeper, inside groups. Grammar test: "SafeDep solves ___" must complete naturally with the tab name. Imperative verbs ("Scan & Analyze") fail; solution nouns ("Package Security") pass.

  • R4 — Concepts are first-class, atomic, linkable. Each concept (Malicious Package, Vulnerability, Policy, CEL, SBOM, Tenant, Endpoint) gets one dedicated page under Get Started › Core Concepts. Malicious-package protection is a solution (the Package Security tab), not a concept: the concept is the malicious package itself, and concepts/malicious-package carries the user-facing detection story (how SafeDep classifies a package as malicious). The Malysis/Malbase pipeline is internal infrastructure, never a concept page, product tab, or sidebar group. If SafeDep's threat-intelligence offering productizes, the user-facing product gets a docs home under the planned Threat Intelligence tab (§8); the pipeline stays invisible. The distinction this rule protects is pipeline vs product, not "intelligence never gets a tab."

  • R5 — Progressive disclosure. Tab depth is unlimited; groups handle it. A tab splits only when it covers fundamentally different security outcomes. The Reference tab is the technical lookup layer — CLI flags, filter syntax, API specs — and is the only place exhaustive lookup content belongs.

  • R6 — docs.safedep.io is the guide layer. Product-level technical reference (CLI flags, type definitions) lives in individual product repos (vet, pmg, etc.). This site covers concepts, how-tos, and integration guides.

  • R7 — AI-agent consumability is first-class. One concept per atomic page, predictable headings, stable URLs. llms.txt / llms-full.txt are auto-generated by Mintlify.

  • R8 — Every product has a landing page. Each product (pmg, Endpoint Hub, Gryph, etc.) gets an overview page that (1) summarizes what the product does and (2) links to its setup docs in sequential order. The landing page is a routing page, not a tutorial — it lets a reader understand the product at a glance and follow a clear path from zero to operational.

  • R9 — Personas inform voice and priority, not structure. Navigation is organized by user need / use-case / Diátaxis mode — never by who the reader is. There are no persona journeys, persona gates, or "choose your role" router pages (that is a marketing-site pattern, not a docs pattern). Personas legitimately influence two things only: (1) page voice — a page is pitched at an assumed reader (a tutorial assumes a beginner; reference assumes a working practitioner), and (2) backlog priority — persona research decides which use-cases we build first (e.g. today, the individual-dev local-install flow). Neither shows up in the tree. Entry routing, where we want it, uses concrete use-case cards ("Stop a malicious npm install," "Block bad packages in CI"), Stripe-style — not roles. Buyer personas don't read docs, so they don't even shape page voice; they live on the marketing site. (Grounding: Diátaxis organizes by need, not audience; Stripe routes entry by developer goal, not persona.)

Test for any new page: What security outcome does this serve? If the answer is "it documents tool X" rather than "it helps someone achieve Y," it is in the wrong place.

3. Where does a new page go?

If the page… Tab Example group
Defines a concept/term used across docs Get Started Core Concepts
Onboards a new user / routes entry points Get Started Introduction (product quickstarts co-locate with their product)
Covers malicious package blocking (install-time or CI/CD) Package Security pmg / MDM / CI/CD Package Blocking
Covers evaluating a package/extension/repo before use (on-demand scanning) Package Security On-Demand Package Scanning
Covers AI agent discovery, audit, or control AI Agent Security AI Agent Observability / AI Coding Protection
Covers scanning repos, SBOMs, or CI/CD for supply-chain risk Visibility & Governance Repository Scanning / Bill of Materials / CI/CD
Covers deploying vet or running vet tasks across endpoint fleets Visibility & Governance MDM
Covers cloud policy, endpoint inventory, or org-wide access Visibility & Governance SafeDep Cloud / Endpoint Hub / Policy & Risk
Covers consuming the malicious-package feed (reports, campaigns, feed API) Threat Intel Getting Started / Consuming the Feed / Reference
Is pure lookup (syntax, flags, API) Reference vet Query & Policy / API & Automation
Is community/support Community & Support Community / Support

A page appears in exactly one sidebar slot. Use an in-body <Card> to surface it from another tab — never a second nav entry.

vet-action / GitHub Actions split: vet-action serves two distinct outcomes. A page about blocking malicious packages in CI/CD belongs in Package Security. A page about scanning repos for risk, generating SBOMs, or enforcing policy in CI/CD belongs in Visibility & Governance. Write one page per outcome.

4. File path convention for new pages

Legacy paths (vet/, pmg/, xbom/, cloud/, apps/, scan/) are grandfathered — do not move them without adding a redirects entry in docs.json.

New pages use solution-aligned paths:

Path prefix Tab
get-started/ Get Started (primer, entry points, quickstart aggregators)
concepts/ Get Started › Core Concepts
package-security/ Package Security
ai-security/ AI Agent Security
governance/ Visibility & Governance
threat-intel/ Threat Intel
reference/ Reference

Path renames require a redirect in docs.json: { "source": "/old", "destination": "/new" }. Verify with node_modules/.bin/mintlify broken-links after every change.

5. Naming, frontmatter, and Diátaxis

File names: kebab-case, specific (github-code-scanning.mdx, not guide.mdx).

Frontmatter (required):

---
title: Descriptive Page Title
description: "Clear, searchable description under 160 characters"
---

No H1 — Mintlify renders the title from frontmatter.

One Diátaxis type per page:

Type Style Location
Tutorial Learning-oriented, hands-on The product's group in its solution tab (quickstart co-located with the product)
How-to Guide Problem-oriented, step-by-step The relevant solution tab
Reference Comprehensive, minimal explanation Reference tab
Explanation Conceptual, connects ideas Get Started › Core Concepts

Don't mix Diátaxis types within a single page.

6. How to change the IA

  1. Update docs.json (the tabs array).
  2. Update this file — §1 table and any changed rule.
  3. Update the Notion mirror.
  4. Update the condensed copy in CLAUDE.md.
  5. If a file path changes, add a redirects entry in docs.json and run node_modules/.bin/mintlify broken-links.

7. Authoritative tab → group → page map

Human-readable mirror of docs.json. Source of truth is docs.json. Re-synced after the Phase 2 path migration, the Phase 3 sidebar restructure, and the net-new pages landed. A group's clickable landing (Mintlify root) is marked (landing).

Get Started

  • Introduction: introduction, get-started/choose-your-path, get-started/cli-tools, get-started/safedep-skill
  • Core Concepts: concepts/malicious-package, concepts/vulnerability, concepts/policy, concepts/cel, concepts/sbom, concepts/tenant, concepts/endpoint

Package Security (tab landing: package-security/overview)

  • Install-Time Package Blocking: package-security/pmg/overview (landing), package-security/pmg/quickstart, package-security/pmg/system-install
  • MDM: package-security/pmg/mdm/overview (landing), package-security/pmg/mdm/jamf, package-security/pmg/mdm/jumpcloud, package-security/pmg/mdm/intune
  • On-Demand Package Scanning: package-security/scan/overview (landing), package-security/scan/quickstart, package-security/scan/automation
  • CI/CD Package Blocking: package-security/pmg/github-actions

AI Agent Security (tab landing: ai-security/overview) — flat list, scoped to securing AI coding agents. The "AI as a software component" pages (Shadow AI in Code, AI Governance) moved to Visibility & Governance, since AI SDKs in your app are a supply-chain concern, not agent security. Order is discover → observe → augment.

  • ai-security/ai-tools-discovery, ai-security/gryph-overview, ai-security/mcp-server

Visibility & Governance (tab landing: governance/overview)

  • Repository Scanning: governance/vet/overview (landing), governance/vet/quickstart, governance/vet/dependency-inventory, governance/vet/dependency-usage, governance/vet/code-analysis
  • MDM: governance/vet/mdm/overview
  • Bill of Materials: governance/xbom/overview (landing), governance/xbom/quickstart, governance/cyclonedx-sbom
  • AI Visibility: governance/ai-governance (landing), governance/shadow-ai-detection, governance/vet/ai-bom
  • CI/CD & Platform Integrations: governance/integrations/overview (landing), governance/integrations/github, governance/integrations/github-code-scanning, governance/integrations/gitlab, governance/integrations/bitbucket, governance/integrations/defectdojo, governance/terraform-audit
  • SafeDep Cloud: governance/cloud/overview (landing), governance/cloud/quickstart, governance/cloud/authentication, governance/cloud/usage-billing, governance/cloud/sync, governance/cloud/talk-to-safedep, governance/cloud/alerts
    • Endpoint Hub: governance/cloud/endpoint-hub/overview (landing), governance/cloud/endpoint-hub/inventory, governance/cloud/endpoint-hub/inventory-catalog, governance/cloud/endpoint-hub/package-guard, governance/cloud/endpoint-hub/mcp-advisor, governance/cloud/endpoint-hub/agentic-investigation
    • Policy & Risk: governance/cloud/malware-analysis, governance/cloud/package-exclusions

Threat Intel (tab landing: threat-intel/overview) — subscription-gated feed API (FEATURE_THREAT_INTEL_FEED). Product-level API guide; threat-intel/schema links out to the public buf.build/safedep/api module for the message/field/enum definitions (R6, don't hand-copy tables that drift). The module is public (a keyless @buf/safedep_api.bufbuild_es install resolves), so no in-page restatement is needed.

  • Getting Started: threat-intel/quickstart, threat-intel/concepts
  • Consuming the Feed: threat-intel/connecting, threat-intel/pagination, threat-intel/package-reports, threat-intel/campaigns, threat-intel/recipes
  • Integrations: threat-intel/integrations/jfrog-xray
  • Reference: threat-intel/schema, threat-intel/errors, threat-intel/sdks

Reference

  • Query & Policy: reference/filtering, reference/build-your-own-queries, reference/policy-as-code, reference/exceptions, reference/path-exclusion
  • API & Automation: reference/api-introduction, reference/endpoints, reference/insights-api-typescript, reference/sql-query

Community & Support

  • Community: community
  • Support: faq, governance/cloud/faq

Total: 82 pages

8. Planned additions (backlog)

New page Destination
concepts/malicious-package Get Started › Core Concepts
concepts/vulnerability Get Started › Core Concepts
concepts/policy Get Started › Core Concepts
concepts/endpoint Get Started › Core Concepts
concepts/tenant Get Started › Core Concepts
concepts/sbom Get Started › Core Concepts
concepts/policy-as-code Get Started › Core Concepts
Section landing pages One per solution tab
governance/tenants-access-control Visibility & Governance › Access & Identity
reference/cli Reference — dry per-command surface; the orientation/"which CLI" map shipped as get-started/cli-tools

Threat Intelligence tab — SHIPPED as "Threat Intel" (2026-08-20)

The productized feed shipped as the Threat Intel tab (path prefix threat-intel/), placed after Visibility & Governance. It documents the subscription-gated Threat Intel Feed API (safedep.services.threatintel.v1.ThreatIntelService, gated on FEATURE_THREAT_INTEL_FEED, served on api.safedep.io). The label was chosen as "Threat Intel" (shorter nav form of the industry category below) over the mechanism-shaped "Feed". Documented RPCs: package reports and campaigns. Snapshots (ListSnapshots, GetSnapshotDownloadUrl) are implemented in the deployed service but intentionally left undocumented until GA/polished; the indicator RPCs (ListIndicators, LookupIndicator) return unimplemented. The scope and rules below remain the governing constraints as the tab grows.

Original planning note (retained for rationale):

Threat Intelligence is expected to productize. When the product ships, it becomes a new solution tab — not before (no empty tabs). Scope and rules:

  • The tab is the solution, not the product. It is scoped to SOC intel-consumption use-cases — alert triage, enrichment, threat hunting, SIEM/SOAR feeds. Product pages sit one level deep inside groups, same as every other tab. Scope test: a second intel-adjacent product must fit this tab without renaming it; if it can't, the tab has become a brand tab and violates R3.
  • Label note (R3): "Threat Intelligence" is grammatically product-shaped ("SafeDep provides TI," not "solves" it), but it is the stable industry category the SOC audience navigates by — the same trade we accepted for "Bill of Materials." Findability wins; the tab's scope stays solution-shaped per the test above.
  • R4 interaction: the Malysis pipeline still never gets a tab; the user-facing TI product does (see amended R4 in §2).
  • R9 guard: the tab is named for the solution, never "For SOC Teams." A distinct consuming team is evidence the outcome is distinct, not the organizing principle.
  • Not a dual-home product: TI does not get nav entries under Package Security or AI Agent Security. Cross-surface from those tabs via in-body <Card>s only.
  • Standard kit on launch (R8/R6): landing page, concept page(s) under Core Concepts, quickstart, integration how-tos, API reference linking to buf.build/safedep/api rather than restating schemas.

Watch items / deferred structural changes (from team review, 2026-06-25)

These are decided or flagged but deliberately out of scope for the IA-revamp PR (that PR fixes what was broken or disorganized; these are larger moves). Tracked here so they are not lost.

  • Concept reclassification (DONE). Standup ruling applied: "malicious package protection" is a solution (the Package Security tab), and malicious package + vulnerability are the core concepts. concepts/malicious-package (carries the detection story) and concepts/vulnerability replace concepts/malicious-package-protection (retired, redirected). R4 rewritten in §2, CLAUDE.md, and the skill. Inbound cards repointed.
  • JFrog Xray placement (DONE). The JFrog Xray integration moved from Package Security to Threat Intel › Integrations (threat-intel/integrations/jfrog-xray). It was the lone paid, registry-level, team-scoped item in a tab that otherwise sells free, no-account, install-time blocking; it now sits with the feed it consumes (the integration is gated on the Threat Intel Feed add-on). Old path /package-security/jfrog-xray redirects to the new one; inbound cards repointed.
  • Visibility & Governance breadth (watch). Six groups span the whole capability ladder, with Endpoint Hub and Policy & Risk nested under SafeDep Cloud. Accepted risk for now; the natural relief valve is the Threat Intelligence tab above, which will draw intel-consumption use-cases out of V&G.
  • Reference how-to misfiles (flagged). reference/build-your-own-queries and reference/insights-api-typescript are how-tos (goal-phrased, step-by-step) sitting in the Reference tab. Diátaxis says how-tos belong in a solution tab (Visibility & Governance). Needs a landing-group decision before moving (redirects required). Interim: a one-line cross-link to the Insights API was added on package-security/overview to serve the "check a package programmatically" use-case.
  • Endpoint Hub: MCP advisor stream (DONE, 2026-07-07). Endpoint Hub has three sources: Inventory (vet endpoint scan), Package Guard (PMG), and Advisor events (SafeDep MCP server). Verified in control-tower services/endpoint_management/list_endpoint_advisor_events.go (mcp_tool_call_logs JOIN endpoints, gated by FEATURE_ENDPOINT_SYNC) and app.safedep.io endpoint-detail Advisor tab. Shipped: (1) dedicated page governance/cloud/endpoint-hub/mcp-advisor (sibling to Package Guard); (2) governance/cloud/endpoint-hub/overview rewritten "two views" → three (Inventory · Package Guard · MCP Advisor), naming the MCP server as the source; (3) Endpoint Hub <Note> + cross-link added to ai-security/mcp-server. Attribution is best-effort via the X-Endpoint-ID header the SafeDep CLI injects (setup mcp install); manual raw-header setup records at tenant level only. Gryph stays local-only (no endpoint link until it gains Cloud sync).