Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude/skills/writing-safedep-docs/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,7 @@ See `products.md` in this skill for: per-product one-liner, source repo path, do
- **pmg** — install-time malicious package blocking → Package Security
- **gryph** — AI coding agent observability / local audit trail (records what the agent does; does **not** block or sandbox) → AI Agent Security
- **xBom** — standalone xBOM/SBOM generator via static code analysis → Visibility & Governance › Bill of Materials
- **MCP** — SafeDep MCP server for AI coding tools → AI Agent Security › AI Coding Protection
- **MCP** — SafeDep MCP server for AI coding tools → AI Agent Security (`ai-security/mcp-server`)
- **vet-action** — GitHub Action; split by use-case (blocking → Package Security; scanning → Visibility & Governance)
- **SafeDep Cloud / Endpoint Hub** — hosted control plane (closed-source) → Visibility & Governance. Public API surface: [`buf.build/safedep/api`](https://buf.build/safedep/api) — canonical schemas + generated SDKs; link to it, don't restate it (R6)
- **Malysis** — intelligence layer; **never a product tab or sidebar group** (R4)
Expand Down
10 changes: 5 additions & 5 deletions .claude/skills/writing-safedep-docs/products.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
- **One-liner (from README):** Real-time malicious package detection and software supply chain security.
- **What it is:** A CLI scanner for open-source dependencies. Detects malicious packages, generates risk reports, runs CEL-based queries and policies, produces SBOMs.
- **Public repo:** `github.com/safedep/vet`
- **Docs home:** **Visibility & Governance › Repository Scanning** (`governance/vet/`). Fleet deployment lives under **Visibility & Governance › MDM** (`governance/vet/mdm/overview`). vet also powers CI/CD & Platform Integrations (vet-action) and the Reference tab (Query & Policy: `reference/filtering`, `policy-as-code`, `sql-query`). Note: the standalone **xBom** product is a separate repo (`github.com/safedep/xbom`), not part of vet.
- **Docs home:** **Visibility & Governance › Repository Scanning** (`governance/vet/`). Fleet deployment is `governance/vet/mdm/overview`, in the same group. vet also powers CI/CD Integrations (vet-action) and the Reference tab (vet Query & Policy: `reference/filtering`, `policy-as-code`). Note: the standalone **xBom** product is a separate repo (`github.com/safedep/xbom`), not part of vet.
- **Key concepts surfaced:** CEL (filtering / queries / policy), Malysis (intelligence backend), Policy-as-Code, SBOM (CycloneDX).
- **Where to read up-to-date facts:** `README.md`, `docs/` in the vet repo; `cmd/` for command surface; `scan.go` / `query.go` for top-level behavior.
- **vet-action note:** Lives under the vet repo (`.github/actions/`) and as `safedep/vet-action`. Split per use-case: blocking → Package Security; scanning/SBOM → Visibility & Governance.
Expand All @@ -23,7 +23,7 @@
- **One-liner (from README):** Block malicious npm and pip packages before they install. Defense in depth for the package managers you already use.
- **What it is:** A wrapper / proxy around `npm` and `pip` (and similar) that intercepts installs and blocks known-malicious packages at the dev machine, before code touches disk.
- **Public repo:** `github.com/safedep/pmg`
- **Docs home:** **Package Security › Install-Time Package Blocking** (`package-security/pmg/`). R8 landing at `package-security/pmg/overview`. Fleet MDM how-tos live under **Package Security › MDM** (`package-security/pmg/mdm/`).
- **Docs home:** **Package Security › Block at Install** (`package-security/pmg/`). R8 landing at `package-security/pmg/overview`. Fleet MDM how-tos live under **Package Security › Deploy to a Fleet** (`package-security/pmg/mdm/`).
- **Key concepts surfaced:** Malysis (intelligence used to decide block/allow), Package Manager interception, Truststore.
- **Where to read up-to-date facts:** `README.md`, `CLAUDE.md`, `AGENTS.md` in the pmg repo; `cmd/` for command surface; `packagemanager/` and `extractor/` for what's supported.
- **Note:** `pmg` and `vet-action` together are the two halves of Package Security — local-machine vs CI/CD. Both block malicious packages; they differ only in *where*.
Expand All @@ -35,7 +35,7 @@
- **One-liner (from repo description):** Security layer for AI coding agents. Works with Claude Code, Cursor, Windsurf, Gemini CLI, OpenCode, Pi Agent and more.
- **What it is:** An **observability / audit** layer for AI coding agents. It *records* what an agent reads, writes, and runs into a **local** audit log. It does **not** block, sandbox, or enforce. Do **not** describe it as a "sandbox", "fence", "guardrail", or anything implying enforcement (the fleet review caught exactly this overstatement). Commands: `gryph logs` (recent activity), `gryph query` (filter the log), `gryph sessions` (list sessions). There is no "replay" feature.
- **Public repo:** `github.com/safedep/gryph`
- **Docs home:** **AI Agent Security › AI Agent Observability**. R8 landing page is live at `ai-security/gryph-overview`.
- **Docs home:** **AI Agent Security**. R8 landing page is live at `ai-security/gryph-overview`.
- **Key concepts surfaced:** AI agent observability, local audit trail. Different from MCP (Gryph *observes* the agent at runtime; MCP exposes SafeDep tools *to* the agent).
- **Where to read up-to-date facts:** `README.md`, `CLAUDE.md`, `AGENTS.md` in the gryph repo; `cli/` and `cmd/` for surface; `agent/` for supported agents.

Expand All @@ -45,7 +45,7 @@

- **One-liner:** A Model Context Protocol (MCP) server that exposes SafeDep's package-intelligence and vet capabilities to AI coding tools (Claude Code, Cursor, etc.) so the agent can ask "is this package safe?" before suggesting `npm install`.
- **What it is:** Not a separate repo — lives inside the vet repo at `mcp/`.
- **Docs home:** **AI Agent Security › AI Coding Protection** (`ai-security/mcp-server`). Hosted endpoint: `mcp.safedep.io`. The `safedep` CLI configures it via `safedep setup mcp install`.
- **Docs home:** **AI Agent Security** (`ai-security/mcp-server`). Hosted endpoint: `mcp.safedep.io`. The `safedep` CLI configures it via `safedep setup mcp install`.
- **Where to read up-to-date facts:** `mcp/` in the vet repo; `safedep-cli` for the `setup mcp` flow.
- **Distinction:** MCP = give SafeDep *to* the AI tool (the agent can ask "is this package safe?"). Gryph = *observe and record* what the AI tool does. Different products, both under AI Agent Security, never conflate them.

Expand All @@ -69,7 +69,7 @@
- **Public repos:** none — the implementation is internal. Document the user-facing surface only (UI flows, API endpoints exposed to users, concepts).
- **Docs home:** **Visibility & Governance**, across the SafeDep Cloud (with Endpoint Hub nested), Cloud Policy, and Access & Identity groups. R2 reminder: Cloud features get a simple `<Note>` callout, **not** a separate persona/tier tab.
- **Plans:** Free, Team, and Enterprise. Never write "Pro" or "Professional": the API enum is `BILLING_TIER_PROFESSIONAL`, but the product, the pricing page, and `safedep subscription status` say Team. The pricing page (`https://safedep.io/pricing`) is the only source of plan data. Do not copy the plan table into the docs. A Cloud feature gets a `<Note>` that names the plan and links to the pricing page. Every PMG and Vet feature is open source, so a Cloud section says what Cloud adds (team-wide visibility, query, alerts), never that the tool feature itself is paid. SIEM integrations and MDM fleet sync are Enterprise. Feature gates live in Control Tower `models/billing_tier.go`.
- **SQL gotcha:** `endpoints.endpoint_type` is always `0` in production (nothing sets it). PMG sets `package_guard_events.ci_provider` only for GitHub Actions (`internal/audit/cloud_env_resolver.go` has one resolver). Filter GitHub Actions events on `ci_provider = 'ENDPOINT_CI_PROVIDER_GITHUB_ACTIONS'`. For other CI systems, filter on an `endpoints.identifier` prefix set with `PMG_CLOUD_ENDPOINT_ID`. The query engine rejects `COUNT(*)`; use `COUNT(column)` or `COUNT(DISTINCT column)`.
- **SQL gotcha:** Control Tower sets `endpoints.endpoint_type` from the PMG session summary (`1` developer machine, `2` CI runner, `4` Kubernetes workload). An endpoint shows `0` until a summary with an invocation context arrives. Enum columns come back as numbers in table and JSON output. PMG sets `package_guard_events.ci_provider` only for GitHub Actions (`internal/audit/cloud_env_resolver.go` has one resolver). Filter GitHub Actions events on `ci_provider = 'ENDPOINT_CI_PROVIDER_GITHUB_ACTIONS'`. For other CI systems, filter on an `endpoints.identifier` prefix set with `PMG_CLOUD_ENDPOINT_ID`. The query engine rejects `COUNT(*)`; use `COUNT(column)` or `COUNT(DISTINCT column)`.
- **Where to read up-to-date facts:** the live product (`app.safedep.io`), the public API reference under `api-reference/` in this docs repo, and any user-facing release notes. Do not document internal services, internal repo names, or non-public endpoints.
- **Public API surface — `buf.build/safedep/api`:** the canonical, public definition of everything you can do with/to SafeDep Cloud. Use it as the source of truth for API capabilities, request/response schemas, and service names:
- API docs: `https://buf.build/safedep/api/docs` (e.g. `main:safedep.services.insights.v2`)
Expand Down
26 changes: 13 additions & 13 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,10 +18,10 @@ The documentation is organized into **7 tabs** — solution tabs at the core, pl
3. **AI Agent Security** — discover, audit, and control what AI agents access and run (MCP, Gryph, vet AI discovery)
4. **Visibility & Governance**: scan repos/SBOMs/CI/CD for risk; deploy fleet tooling; manage policy and cloud visibility (vet, xBom, SafeDep Cloud, Endpoint Hub, Endpoint Sync, Cloud Policy)
5. **Threat Intel** — consume the malicious-package feed as an API: reports and campaigns (ThreatIntelService). Subscription-gated (`FEATURE_THREAT_INTEL_FEED`)
6. **Reference** — exact syntax/APIs (vet query & policy, API & automation)
6. **Reference** — exact syntax/APIs (vet query & policy, cloud policy, Endpoint Hub, API & automation)
7. **Community & Support** — community resources, FAQ and the changelog

> **Status:** the IA migration is complete. The 6-tab structure is live in `docs.json`, and all pages have moved to solution-aligned paths (`get-started/`, `concepts/`, `package-security/`, `ai-security/`, `governance/`, `reference/`). Old paths (`vet/`, `pmg/`, `cloud/`, `apps/`, `scan/`, `xbom/`, `api-reference/`) are **redirects** in `docs.json` `redirects[]`, not live files. When you add or move a page, add its redirect there too.
> **Status:** the IA migration is complete. The 7-tab structure is live in `docs.json`, and all pages have moved to solution-aligned paths (`get-started/`, `concepts/`, `package-security/`, `ai-security/`, `governance/`, `threat-intel/`, `reference/`). Old paths (`vet/`, `pmg/`, `cloud/`, `apps/`, `scan/`, `xbom/`, `api-reference/`) are **redirects** in `docs.json` `redirects[]`, not live files. When you add or move a page, add its redirect there too.

### Governing Rules (how the IA evolves)

Expand All @@ -30,7 +30,7 @@ Every placement decision derives from these rules. Full rationale and page map:
- **R1 — One primary entry point.** New visitors meet a clear "What is SafeDep?" primer, not a tool catalog.
- **R2 — Capability ladder, not persona gate.** The journey runs: individual dev → team → org-wide governance. Navigation doesn't pin users to a tier. Features requiring SafeDep Cloud are marked with a `<Note>` callout — no structural separation.
- **R3 — Organize by solution, not by tool.** Tabs name the security outcome SafeDep delivers. Grammar test: "SafeDep solves ___" must complete naturally with the tab name.
- **R4: Concepts are first-class, atomic, linkable.** Each concept gets one dedicated page under Get Started › Core Concepts (`concepts/`). The eleven that exist: `malicious-package`, `vulnerability`, `policy`, `policy-resolution`, `labels`, `package-rules`, `policy-revisions`, `cel`, `sbom`, `tenant`, `endpoint`. The policy concepts and `cel` sit in a nested "Policy" group, the last entry of Core Concepts, after the flat pages. **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). Malysis/Malbase are **not** concept pages. They are internal infrastructure (R6). The Malysis *pipeline* is never a product tab. A productized Threat Intelligence offering gets its own solution tab (shipped as the **Threat Intel** tab, `threat-intel/`; see `docs-ia.md` §8). The rule protects pipeline vs product.
- **R4: Concepts are first-class, atomic, linkable.** Each concept gets one dedicated page under Get Started › Core Concepts (`concepts/`). The eleven that exist: `malicious-package`, `vulnerability`, `policy`, `policy-resolution`, `labels`, `package-rules`, `policy-revisions`, `cel`, `sbom`, `tenant`, `endpoint`. `policy` and `cel` are flat pages. The four cloud policy concepts (`policy-resolution`, `labels`, `package-rules`, `policy-revisions`) sit in a nested "Cloud Policy" group, the last entry of 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). Malysis/Malbase are **not** concept pages. They are internal infrastructure (R6). The Malysis *pipeline* is never a product tab. A productized Threat Intelligence offering gets its own solution tab (shipped as the **Threat Intel** tab, `threat-intel/`; see `docs-ia.md` §8). The rule protects pipeline vs product.
- **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 only place for exhaustive lookup content.
- **R6 — docs.safedep.io is the guide layer.** Product-level technical reference (CLI flags, type definitions) lives in individual product repos. 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.
Expand All @@ -45,19 +45,19 @@ Every placement decision derives from these rules. Full rationale and page map:
|---|---|---|
| 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, CI/CD for risk | Visibility & Governance | Repository Scanning / Bill of Materials / CI/CD |
| Covers deploying vet or running vet tasks across endpoint fleets | Visibility & Governance | MDM |
| Covers malicious package blocking (install-time or CI/CD) | Package Security | Block at Install / Deploy to a Fleet / Block in CI/CD |
| Covers evaluating a package/extension/repo before use (on-demand scanning) | Package Security | Scan Before Use |
| Covers AI agent discovery, audit, or control | AI Agent Security | Flat page list (no groups) |
| Covers scanning repos, SBOMs, CI/CD for risk | Visibility & Governance | Repository Scanning / Bill of Materials / CI/CD Integrations |
| Covers deploying vet or running vet tasks across endpoint fleets | Visibility & Governance | Repository Scanning (`governance/vet/mdm/overview`) |
| Covers endpoint inventory or org-wide access in SafeDep Cloud | Visibility & Governance | SafeDep Cloud / Endpoint Hub |
| Changes a cloud policy setting, package rule or policy module | Visibility & Governance | Cloud Policy (one subgroup per capability when there is more than one) |
| Connects or sets up a tool that enforces the cloud policy | That tool's outcome tab | The tool's group, with a card from Cloud Policy |
| Is an independent capability with its own data and workflow that the policy only references (for example a catalog of approved components) | Visibility & Governance | Its own group |
| 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 |
| Covers consuming the malicious-package feed (reports, campaigns, feed API) | Threat Intel | Getting Started / Use the Feed / Schema & Errors |
| Is pure lookup (syntax, flags, API) | Reference | vet Query & Policy / Cloud Policy / Endpoint Hub / API & Automation |
| Is community/support | Community & Support | Community / Support |
| Records what SafeDep shipped (changelog) | Community & Support | Updates (`changelog/<year>.mdx`: use the `writing-changelog` skill) |
| Records what SafeDep shipped (changelog) | Community & Support | Changelog (`changelog/<year>.mdx`: use the `writing-changelog` skill) |

A page appears in **exactly one** sidebar slot. To surface it from another tab, add an in-body `<Card>` — never a second nav entry.

Expand All @@ -71,7 +71,7 @@ All documentation follows the **Diátaxis framework** with four content types:

1. **Tutorials** (`introduction.mdx`, `*/quickstart.mdx`) — Learning-oriented, hands-on. Live in Get Started or at the top of a solution tab.
2. **How-to Guides** — Live in the relevant solution tab (Package Security / AI Agent Security / Visibility & Governance):
- CI/CD & Platform Integrations: GitHub, GitLab, Bitbucket, JFrog, DefectDojo
- CI/CD Integrations: GitHub, GitLab, Bitbucket, JFrog, DefectDojo
- SBOM & Analysis: CycloneDX, dependency inventory, code analysis
- API & Automation: TypeScript API usage, Terraform audits
3. **Reference** (`reference/`) — Technical specifications and lookup. All live in the **Reference** tab.
Expand Down Expand Up @@ -211,7 +211,7 @@ Example — adding a new CI/CD integration guide:
"tab": "Visibility & Governance",
"groups": [
{
"group": "CI/CD & Platform Integrations",
"group": "CI/CD Integrations",
"pages": [
"governance/integrations/overview",
"governance/integrations/github-code-scanning",
Expand Down
6 changes: 3 additions & 3 deletions concepts/tenant.mdx
Original file line number Diff line number Diff line change
@@ -1,16 +1,16 @@
---
title: Tenant
description: "A tenant is your organization's isolated space in SafeDep Cloud, identified by its tenant domain such as your-company.safedep.io."
description: "A tenant is your organization's isolated space in SafeDep Cloud, identified by its tenant domain such as your-team.your-org.safedep.io."
---

A tenant is your organization's isolated space in SafeDep Cloud. Your users, API keys, policies, scan data, and endpoints all live inside it, separate from every other tenant.

## Your tenant ID is your tenant domain

The tenant identifier is a domain, for example `your-company.safedep.io`. There is no separate tenant ID to look up. You use the domain to:
The tenant identifier is a domain with three parts: `<team>.<organization>.safedep.io`, for example `your-team.your-org.safedep.io`. The **Tenant ID** button on the [API keys settings page](https://app.safedep.io/settings/api-keys) shows your tenant domain. There is no separate tenant ID to look up. You use the domain to:

- send the `X-Tenant-ID` header on API requests,
- configure Vet with `vet auth configure --tenant your-company.safedep.io`,
- configure Vet with `vet auth configure --tenant your-team.your-org.safedep.io`,
- set the `SAFEDEP_TENANT_ID` environment variable.

## Why it matters
Expand Down
Loading
Loading