From 6271a4cd35554b2de2e1bc67f9e0fb7e73c5b5bf Mon Sep 17 00:00:00 2001 From: Sahilb315 Date: Wed, 11 Nov 2026 21:43:34 +0530 Subject: [PATCH] Fix the findings from the review of PRs 122 to 127 - SQL: endpoint_type values, enums as numbers, last-page token, sandbox table, count(*) - Add PMG_PACKAGE_ACTION_RULE_BLOCKED to the block queries - Use the three-part tenant domain form everywhere - Fix the Shadow AI example, GitHub App check line, and anchors - Sync CLAUDE.md, docs-ia.md and the docs skill with docs.json Co-Authored-By: Claude Opus 5.5 --- .claude/skills/writing-safedep-docs/SKILL.md | 2 +- .../skills/writing-safedep-docs/products.md | 10 ++--- CLAUDE.md | 26 +++++------ concepts/tenant.mdx | 6 +-- docs-ia.md | 44 +++++++++---------- docs.json | 2 +- downloads/ingest-sd-ngsiem.py | 2 +- governance/cloud/alerts.mdx | 10 +++-- governance/cloud/authentication.mdx | 10 ++--- governance/cloud/crowdstrike-siem.mdx | 6 +-- .../endpoint-hub/agentic-investigation.mdx | 6 +-- .../cloud/endpoint-hub/ci-package-blocks.mdx | 10 +++-- governance/cloud/endpoint-hub/inventory.mdx | 4 +- governance/cloud/faq.mdx | 1 - governance/cloud/query-with-sql.mdx | 21 +++++---- governance/cloud/quickstart.mdx | 2 +- governance/cloud/sync.mdx | 4 +- governance/integrations/github.mdx | 2 +- governance/shadow-ai-detection.mdx | 5 ++- governance/vet/code-analysis.mdx | 5 ++- package-security/scan/automation.mdx | 6 +-- reference/api-introduction.mdx | 2 +- reference/endpoints.mdx | 2 +- reference/sql-query.mdx | 13 ++++-- threat-intel/connecting.mdx | 6 +-- threat-intel/integrations/jfrog-xray.mdx | 4 +- threat-intel/pagination.mdx | 2 +- threat-intel/quickstart.mdx | 4 +- threat-intel/sdks.mdx | 4 +- 29 files changed, 120 insertions(+), 101 deletions(-) diff --git a/.claude/skills/writing-safedep-docs/SKILL.md b/.claude/skills/writing-safedep-docs/SKILL.md index de23b5d..e26e24e 100644 --- a/.claude/skills/writing-safedep-docs/SKILL.md +++ b/.claude/skills/writing-safedep-docs/SKILL.md @@ -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) diff --git a/.claude/skills/writing-safedep-docs/products.md b/.claude/skills/writing-safedep-docs/products.md index 4b8a87e..8047bff 100644 --- a/.claude/skills/writing-safedep-docs/products.md +++ b/.claude/skills/writing-safedep-docs/products.md @@ -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. @@ -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*. @@ -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. @@ -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. @@ -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 `` 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 `` 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`) diff --git a/CLAUDE.md b/CLAUDE.md index c6c5d0e..40e3a1e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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) @@ -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 `` 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. @@ -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/.mdx`: use the `writing-changelog` skill) | +| Records what SafeDep shipped (changelog) | Community & Support | Changelog (`changelog/.mdx`: use the `writing-changelog` skill) | A page appears in **exactly one** sidebar slot. To surface it from another tab, add an in-body `` — never a second nav entry. @@ -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. @@ -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", diff --git a/concepts/tenant.mdx b/concepts/tenant.mdx index 3b78164..b638295 100644 --- a/concepts/tenant.mdx +++ b/concepts/tenant.mdx @@ -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: `..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 diff --git a/docs-ia.md b/docs-ia.md index cbf517c..77e1f4d 100644 --- a/docs-ia.md +++ b/docs-ia.md @@ -12,15 +12,15 @@ Seven tabs — solution tabs at the core, plus supporting tabs. | Tab | Purpose | Groups | |---|---|---| -| **Get Started** | What is SafeDep, vocabulary, entry points | Introduction · Core Concepts (nests Policy) | -| **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) · Cloud Policy | -| **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, changelog | Community · Support · Updates | +| **Get Started** | What is SafeDep, vocabulary, entry points | Introduction · Core Concepts (nests Cloud Policy) | +| **Package Security** | Block malicious packages at install time — on dev machines and in CI/CD — and scan any component on demand before use | Block at Install · Deploy to a Fleet · Block in CI/CD · Scan Before Use | +| **AI Agent Security** | Discover, audit, and control what AI agents access and run | Flat page list (no groups) | +| **Visibility & Governance** | Scan repos, SBOMs, and CI/CD for supply-chain risk; deploy fleet tooling; manage policy and org-wide cloud visibility | Repository Scanning · Bill of Materials · AI Visibility · CI/CD Integrations · SafeDep Cloud (nests Set Up, Endpoint Hub, Investigate, Integrate, Account) · Cloud Policy | +| **Threat Intel** | Consume the malicious-package feed as an API: reports and campaigns. Subscription-gated (`FEATURE_THREAT_INTEL_FEED`) | Getting Started · Use the Feed · Integrations · Schema & Errors | +| **Reference** | Exact syntax, flags, API specs — no explanation | vet Query & Policy · Cloud Policy · Endpoint Hub · API & Automation | +| **Community & Support** | Community resources, FAQ, changelog | Community · Support · Changelog | -> **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. +> **Implementation note:** the 7-tab structure is live in `docs.json`, and all pages are at solution-aligned paths. Legacy paths (`vet/`, `cloud/`, `apps/`, `xbom/`) exist only as redirects. --- @@ -34,7 +34,7 @@ Every structural decision derives from these rules. Full rationale in `docs-ia-p - **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, Policy Resolution, Labels, Package Rules, Policy Revisions, CEL, SBOM, Tenant, Endpoint) gets one dedicated page under Get Started › Core Concepts. 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). 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." +- **R4: Concepts are first-class, atomic, linkable.** Each concept (Malicious Package, Vulnerability, Policy, Policy Resolution, Labels, Package Rules, Policy Revisions, CEL, SBOM, Tenant, Endpoint) gets one dedicated page under Get Started › Core Concepts. 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). 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. @@ -56,19 +56,19 @@ Every structural decision derives from these rules. Full rationale in `docs-ia-p |---|---|---| | 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 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, or CI/CD for supply-chain 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 (example: `package-security/pmg/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/`, one page for each year, written with the `writing-changelog` skill) | +| Records what SafeDep shipped (changelog) | Community & Support | Changelog (`changelog/`, one page for each year, written with the `writing-changelog` skill) | A page appears in **exactly one** sidebar slot. Use an in-body `` to surface it from another tab — never a second nav entry. @@ -138,8 +138,8 @@ Don't mix Diátaxis types within a single page. **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/sbom`, `concepts/tenant`, `concepts/endpoint`, `concepts/cel` - - Cloud Policy: `concepts/policy`, `concepts/policy-resolution`, `concepts/labels`, `concepts/package-rules`, `concepts/policy-revisions` +- Core Concepts: `concepts/malicious-package`, `concepts/vulnerability`, `concepts/sbom`, `concepts/tenant`, `concepts/endpoint`, `concepts/policy`, `concepts/cel` + - Cloud Policy: `concepts/policy-resolution`, `concepts/labels`, `concepts/package-rules`, `concepts/policy-revisions` **Package Security** *(tab landing: `package-security/overview`)* - Block at Install: `package-security/pmg/overview` *(landing)*, `package-security/pmg/quickstart`, `package-security/pmg/sandbox`, `package-security/pmg/network-policy`, `package-security/pmg/dependency-cooldown`, `package-security/pmg/cloud-policy`, `package-security/pmg/private-registries` @@ -161,7 +161,7 @@ Don't mix Diátaxis types within a single page. - Investigate: `governance/cloud/endpoint-hub/agentic-investigation`, `governance/cloud/query-with-sql` - Integrate: `governance/cloud/alerts`, `governance/cloud/crowdstrike-siem` - Account: `governance/cloud/usage-billing` -- Cloud Policy: `governance/cloud/policy/overview` *(landing)*, `governance/cloud/policy/quickstart`, `governance/cloud/policy/block-a-package`, `governance/cloud/policy/trust-a-package`, `governance/cloud/policy/set-a-cooldown`, `governance/cloud/policy/target-a-group`, `governance/cloud/policy/pull-request-checks`, `governance/cloud/policy/roll-back-a-change`, `governance/cloud/policy/explain-a-decision`, `governance/cloud/policy/audit-policy-changes`, `governance/cloud/package-exclusions` +- Cloud Policy: `governance/cloud/policy/overview` *(landing)*, `governance/cloud/policy/quickstart`, `governance/cloud/policy/block-a-package`, `governance/cloud/policy/trust-a-package`, `governance/cloud/policy/set-a-cooldown`, `governance/cloud/policy/target-a-group`, `governance/cloud/policy/pull-request-checks`, `governance/cloud/policy/roll-back-a-change`, `governance/cloud/policy/explain-a-decision`, `governance/cloud/policy/audit-policy-changes`, `governance/cloud/package-exclusions` (deprecated: package rules replace it) **Threat Intel** *(tab landing: `threat-intel/overview`)* - Getting Started: `threat-intel/quickstart`, `threat-intel/concepts` @@ -178,7 +178,7 @@ Don't mix Diátaxis types within a single page. **Community & Support** - Community: `community` - Support: `governance/vet/faq` -- Changelog: `changelog/2026` +- Changelog: `changelog/2026` (`/changelog` redirects to the current year) Notes: - AI Agent Security is scoped to securing AI coding *agents*. AI SDKs inside your application are a supply-chain concern, so Shadow AI Detection (which also covers the AI BOM) sits in Visibility & Governance › AI Visibility. It keeps its own page and URL because people search for "shadow AI". @@ -225,5 +225,5 @@ These are decided or flagged but deliberately out of scope for the IA-revamp PR - **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).** Seven groups span the whole capability ladder, with Endpoint Hub nested under SafeDep Cloud and Cloud Policy as its own group. 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. +- **Reference how-to misfiles (flagged).** `reference/insights-api-typescript` is a how-to (goal-phrased, step-by-step) sitting in the Reference tab. `build-your-own-queries` already moved to `governance/vet/`. 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 `` + 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). diff --git a/docs.json b/docs.json index 0d7d4da..11edbdc 100644 --- a/docs.json +++ b/docs.json @@ -48,12 +48,12 @@ "concepts/sbom", "concepts/tenant", "concepts/endpoint", + "concepts/policy", "concepts/cel", { "group": "Cloud Policy", "icon": "scale-balanced", "pages": [ - "concepts/policy", "concepts/policy-resolution", "concepts/labels", "concepts/package-rules", diff --git a/downloads/ingest-sd-ngsiem.py b/downloads/ingest-sd-ngsiem.py index c3b4e38..70bef4f 100644 --- a/downloads/ingest-sd-ngsiem.py +++ b/downloads/ingest-sd-ngsiem.py @@ -10,7 +10,7 @@ Environment: SAFEDEP_TOKEN required. OAuth token from `safedep auth token`. - SAFEDEP_TENANT_ID required. Tenant domain, e.g. your-company.safedep.io + SAFEDEP_TENANT_ID required. Tenant domain, e.g. your-team.your-org.safedep.io SAFEDEP_CLOUD_URL optional. Default https://cloud.safedep.io CROWDSTRIKE_HEC_URL optional. HEC collector URL, e.g. https:///services/collector. Unset = log only. diff --git a/governance/cloud/alerts.mdx b/governance/cloud/alerts.mdx index e695b36..1e08f91 100644 --- a/governance/cloud/alerts.mdx +++ b/governance/cloud/alerts.mdx @@ -69,7 +69,8 @@ FROM package_guard_events JOIN endpoints ON endpoints.id = package_guard_events.invocation_id WHERE package_guard_events.package_action IN ( 'PMG_PACKAGE_ACTION_BLOCKED', - 'PMG_PACKAGE_ACTION_COOLDOWN_BLOCKED' + 'PMG_PACKAGE_ACTION_COOLDOWN_BLOCKED', + 'PMG_PACKAGE_ACTION_RULE_BLOCKED' ) ORDER BY package_guard_events.timestamp DESC ``` @@ -79,6 +80,8 @@ Two things to notice: - **`package_action` filter.** `PMG_PACKAGE_ACTION_BLOCKED` is a malicious-package block. `PMG_PACKAGE_ACTION_COOLDOWN_BLOCKED` is a cooldown-window block (packages held back until they age past your cooldown threshold). + `PMG_PACKAGE_ACTION_RULE_BLOCKED` is a block by a block entry of the cloud + policy or of the local PMG block list. - **`JOIN endpoints`.** Each block event was produced by a PMG invocation on some developer machine or CI runner. Joining `endpoints` gives you the endpoint's human-readable name (`endpoints.identifier`) and its ID @@ -110,7 +113,7 @@ Save this as `format.py`: import json, sys from urllib.parse import quote -ACTION = {1: ("🔴", "MALICIOUS"), 4: ("🟡", "COOLDOWN")} +ACTION = {1: ("🔴", "MALICIOUS"), 4: ("🟡", "COOLDOWN"), 6: ("🟠", "BLOCK RULE")} ECOSYSTEM = { 1: ("ECOSYSTEM_MAVEN", "Maven"), 2: ("ECOSYSTEM_NPM", "npm"), @@ -202,7 +205,8 @@ PAYLOAD=$(safedep query exec -o json --limit 10 --sql " JOIN endpoints ON endpoints.id = package_guard_events.invocation_id WHERE package_guard_events.package_action IN ( 'PMG_PACKAGE_ACTION_BLOCKED', - 'PMG_PACKAGE_ACTION_COOLDOWN_BLOCKED' + 'PMG_PACKAGE_ACTION_COOLDOWN_BLOCKED', + 'PMG_PACKAGE_ACTION_RULE_BLOCKED' ) AND package_guard_events.timestamp > '$SINCE' ORDER BY package_guard_events.timestamp DESC " | python3 format.py) diff --git a/governance/cloud/authentication.mdx b/governance/cloud/authentication.mdx index 849e24b..65308e4 100644 --- a/governance/cloud/authentication.mdx +++ b/governance/cloud/authentication.mdx @@ -3,7 +3,7 @@ title: Authentication description: "How SafeDep Cloud authentication works and how to authenticate the safedep CLI, vet, and CI/CD pipelines" --- -Every tool that talks to SafeDep Cloud authenticates with two values: a **tenant domain** (for example `your-company.safedep.io`) and a credential. The credential type depends on which API plane the tool calls: +Every tool that talks to SafeDep Cloud authenticates with two values: a **tenant domain** (for example `your-team.your-org.safedep.io`, shown by the **Tenant ID** button on the [API keys settings page](https://app.safedep.io/settings/api-keys)) and a credential. The credential type depends on which API plane the tool calls: - **Data plane** (`api.safedep.io`): package insights, known-malicious package queries, and sync. Authenticates with an **API key**. - **Control plane** (`cloud.safedep.io`): tenant, policy, and management operations, including SQL queries and [on-demand package scans](/package-security/scan/overview). Authenticates with a **JWT** from an OAuth2 login. @@ -22,7 +22,7 @@ safedep auth status For non-interactive environments, log in with a static API key instead of the device flow: ```bash -safedep auth login --api-key --tenant your-company.safedep.io +safedep auth login --api-key --tenant your-team.your-org.safedep.io ``` The key is read from `--api-key-value`, stdin (with `--from-stdin`), the `SAFEDEP_API_KEY` environment variable, or an interactive prompt, in that order. Work with multiple tenants using `--profile` and `safedep auth profile list`. See the [CLI command reference](https://github.com/safedep/cli/tree/main/docs/cmd) for all flags. @@ -36,7 +36,7 @@ API-key login covers data-plane commands only. [On-demand package scanning](/pac vet uses an API key for scanning and [sync](/governance/cloud/sync): ```bash -vet auth configure --tenant your-company.safedep.io +vet auth configure --tenant your-team.your-org.safedep.io ``` You will be prompted to enter the API key. Verify the connection: @@ -48,7 +48,7 @@ vet auth verify Control plane commands under `vet cloud` use the OAuth2 device flow instead: ```bash -vet cloud login --tenant your-company.safedep.io +vet cloud login --tenant your-team.your-org.safedep.io vet cloud whoami ``` @@ -60,7 +60,7 @@ Tools read credentials from environment variables, so pipelines need no interact ```bash export SAFEDEP_API_KEY=your-api-key -export SAFEDEP_TENANT_ID=your-company.safedep.io +export SAFEDEP_TENANT_ID=your-team.your-org.safedep.io ``` Store both as CI secrets. Across SafeDep docs, the secret names are `SAFEDEP_CLOUD_API_KEY` and `SAFEDEP_CLOUD_TENANT_DOMAIN`. [vet-action](https://github.com/safedep/vet-action) reads them through its `cloud-key` and `cloud-tenant` inputs instead of environment variables. diff --git a/governance/cloud/crowdstrike-siem.mdx b/governance/cloud/crowdstrike-siem.mdx index b52811e..dee8d3c 100644 --- a/governance/cloud/crowdstrike-siem.mdx +++ b/governance/cloud/crowdstrike-siem.mdx @@ -28,7 +28,7 @@ Collect these before you start: export SAFEDEP_TOKEN=$(safedep auth token) ``` -- `SAFEDEP_TENANT_ID`: your SafeDep tenant domain, for example `your-company.safedep.io`. +- `SAFEDEP_TENANT_ID`: your SafeDep tenant domain, for example `your-team.your-org.safedep.io`. - `CROWDSTRIKE_HEC_URL`: your CrowdStrike HEC ingest URL, for example `https:///services/collector`. - `CROWDSTRIKE_HEC_TOKEN`: your CrowdStrike HEC token. @@ -44,7 +44,7 @@ Set the environment variables and run the script: ```bash export SAFEDEP_TOKEN=$(safedep auth token) -export SAFEDEP_TENANT_ID=your-company.safedep.io +export SAFEDEP_TENANT_ID=your-team.your-org.safedep.io export CROWDSTRIKE_HEC_URL=https:///services/collector export CROWDSTRIKE_HEC_TOKEN= @@ -141,7 +141,7 @@ Cooldown events carry a `cooldown` object instead of the malware fields: | Variable | Required | Default | Description | |---|---|---|---| | `SAFEDEP_TOKEN` | yes | - | SafeDep OAuth token. Get it with `safedep auth token`. | -| `SAFEDEP_TENANT_ID` | yes | - | Tenant domain, e.g. `your-company.safedep.io`. | +| `SAFEDEP_TENANT_ID` | yes | - | Tenant domain, e.g. `your-team.your-org.safedep.io`. | | `SAFEDEP_CLOUD_URL` | no | `https://cloud.safedep.io` | SafeDep Cloud base URL. | | `CROWDSTRIKE_HEC_URL` | no | (unset) | HEC collector URL, e.g. `https:///services/collector`. Unset means log only. | | `CROWDSTRIKE_HEC_TOKEN` | no | (unset) | HEC ingest token. Required when `CROWDSTRIKE_HEC_URL` is set. | diff --git a/governance/cloud/endpoint-hub/agentic-investigation.mdx b/governance/cloud/endpoint-hub/agentic-investigation.mdx index 0d61a88..37532f6 100644 --- a/governance/cloud/endpoint-hub/agentic-investigation.mdx +++ b/governance/cloud/endpoint-hub/agentic-investigation.mdx @@ -94,7 +94,7 @@ Each row is one decision on one endpoint. `PMG_PACKAGE_ACTION_BLOCKED` means PMG What did PMG block across our endpoints this month? Group it by endpoint. ``` -The agent filters `package_guard_events` on both block actions, bounds the time range to the month, and joins to `endpoints`: +The agent filters `package_guard_events` on the three block actions, bounds the time range to the month, and joins to `endpoints`: ```sql @@ -103,13 +103,13 @@ SELECT endpoints.identifier, package_guard_events.package_name, package_guard_events.timestamp FROM package_guard_events JOIN endpoints ON endpoints.id = package_guard_events.invocation_id -WHERE package_guard_events.package_action IN ('PMG_PACKAGE_ACTION_BLOCKED', 'PMG_PACKAGE_ACTION_COOLDOWN_BLOCKED') +WHERE package_guard_events.package_action IN ('PMG_PACKAGE_ACTION_BLOCKED', 'PMG_PACKAGE_ACTION_COOLDOWN_BLOCKED', 'PMG_PACKAGE_ACTION_RULE_BLOCKED') AND package_guard_events.timestamp >= '2026-08-01T00:00:00Z' ORDER BY package_guard_events.timestamp DESC ``` -`PMG_PACKAGE_ACTION_BLOCKED` is a block on a known malicious package. `PMG_PACKAGE_ACTION_COOLDOWN_BLOCKED` is a block on a package too new to trust under the cooldown policy. Both stopped an install. +`PMG_PACKAGE_ACTION_BLOCKED` is a block on a known malicious package. `PMG_PACKAGE_ACTION_COOLDOWN_BLOCKED` is a block on a package too new to trust under the cooldown policy. `PMG_PACKAGE_ACTION_RULE_BLOCKED` is a block by a block entry of the cloud policy or of the local PMG block list. All three stopped an install. A block on one endpoint is often the first visible event of a campaign. Follow up with the exposure playbook above for the same package across the fleet. diff --git a/governance/cloud/endpoint-hub/ci-package-blocks.mdx b/governance/cloud/endpoint-hub/ci-package-blocks.mdx index 1e04d3d..7ea3951 100644 --- a/governance/cloud/endpoint-hub/ci-package-blocks.mdx +++ b/governance/cloud/endpoint-hub/ci-package-blocks.mdx @@ -34,7 +34,7 @@ PMG in CI blocks a malicious package and fails the job. One failed job shows one ## Review all pipelines -PMG records the CI provider for GitHub Actions jobs. This query lists the malicious package blocks and the cooldown holds in all GitHub Actions jobs: +PMG records the CI provider for GitHub Actions jobs. This query lists the malicious package blocks, the cooldown holds and the block entry blocks in all GitHub Actions jobs: ```sql SELECT endpoints.identifier, @@ -45,7 +45,8 @@ FROM package_guard_events JOIN endpoints ON endpoints.id = package_guard_events.invocation_id WHERE package_guard_events.ci_provider = 'ENDPOINT_CI_PROVIDER_GITHUB_ACTIONS' AND package_guard_events.package_action IN ( - 'PMG_PACKAGE_ACTION_BLOCKED', 'PMG_PACKAGE_ACTION_COOLDOWN_BLOCKED') + 'PMG_PACKAGE_ACTION_BLOCKED', 'PMG_PACKAGE_ACTION_COOLDOWN_BLOCKED', + 'PMG_PACKAGE_ACTION_RULE_BLOCKED') ORDER BY package_guard_events.timestamp DESC ``` @@ -53,7 +54,7 @@ Run it from **Query** in the sidebar, or with `safedep query exec --sql-file`. SafeDep Cloud query console with the package blocks in all GitHub Actions jobs -The console shows enum columns as numbers. In `package_action`, `1` is a malicious package block and `4` is a cooldown hold. +The console shows enum columns as numbers. In `package_action`, `1` is a malicious package block, `4` is a cooldown hold and `6` is a block by a block entry. ### Other CI systems @@ -68,7 +69,8 @@ FROM package_guard_events JOIN endpoints ON endpoints.id = package_guard_events.invocation_id WHERE endpoints.identifier LIKE 'ci-%' AND package_guard_events.package_action IN ( - 'PMG_PACKAGE_ACTION_BLOCKED', 'PMG_PACKAGE_ACTION_COOLDOWN_BLOCKED') + 'PMG_PACKAGE_ACTION_BLOCKED', 'PMG_PACKAGE_ACTION_COOLDOWN_BLOCKED', + 'PMG_PACKAGE_ACTION_RULE_BLOCKED') ORDER BY package_guard_events.timestamp DESC ``` diff --git a/governance/cloud/endpoint-hub/inventory.mdx b/governance/cloud/endpoint-hub/inventory.mdx index 5bf2c1b..fdd8f96 100644 --- a/governance/cloud/endpoint-hub/inventory.mdx +++ b/governance/cloud/endpoint-hub/inventory.mdx @@ -31,13 +31,13 @@ Endpoint inventory shows what AI tooling is active across your endpoints (develo vet auth configure --tenant ``` - The command asks for your **API key**. Then check the credentials: + The tenant domain looks like `your-team.your-org.safedep.io`. The **Tenant ID** button on the [API keys settings page](https://app.safedep.io/settings/api-keys) shows it. The command asks for your **API key**. Then check the credentials: ```bash vet auth verify ``` - To use environment variables instead, or to fix an error, see [Authentication](/governance/cloud/authentication#vet). + To use environment variables instead, see [CI/CD pipelines](/governance/cloud/authentication#cicd-pipelines). To fix an error, see [Troubleshooting](/governance/cloud/authentication#troubleshooting). diff --git a/governance/cloud/faq.mdx b/governance/cloud/faq.mdx index 6949eff..605e445 100644 --- a/governance/cloud/faq.mdx +++ b/governance/cloud/faq.mdx @@ -170,7 +170,6 @@ WARN[0001] Failed to sync data to cloud: project not found **Solution:** - Verify project name and version are correctly specified -- Ensure project names don't contain invalid characters - Check that tenant has permissions for data sync - Ensure API key includes sync permissions - Retry with proper project identification diff --git a/governance/cloud/query-with-sql.mdx b/governance/cloud/query-with-sql.mdx index 1d10bfd..0d20061 100644 --- a/governance/cloud/query-with-sql.mdx +++ b/governance/cloud/query-with-sql.mdx @@ -214,15 +214,19 @@ safedep query exec --sql " ``` endpoints.identifier endpoint_type trust_level last_sync_at -Vignesh 0 1 2026-06-05T07:23:03Z -CICD_GHA_SAFEDEP_CLI 0 1 2026-06-05T06:11:20Z +Vignesh 1 1 2026-06-05T07:23:03Z +CICD_GHA_SAFEDEP_CLI 2 1 2026-06-05T06:11:20Z macbookpro.lan 0 1 2026-06-04T08:54:03Z ``` The `endpoint_type` and `trust_level` enums are not groupable, so use `WHERE` -filters and listings rather than `GROUP BY` for endpoints. SafeDep Cloud does not -set `endpoint_type` yet, so every endpoint shows `0`. To find CI events, filter -on `package_guard_events.ci_provider IS NOT NULL`. +filters and listings rather than `GROUP BY` for endpoints. + +SafeDep Cloud sets `endpoint_type` from the PMG session summary: `1` is a +developer machine, `2` is a CI runner and `4` is a Kubernetes workload. An +endpoint shows `0` until PMG sends a session summary with its runtime context. +PMG detects only GitHub Actions as CI, so a job in another CI system shows `1`. +To find CI events, filter on `package_guard_events.ci_provider IS NOT NULL`. @@ -276,8 +280,9 @@ Sahils-MacBook-Pro.local prettier 2 Sahils-MacBook-Pro.local fast-check 2 pmg 2026-05-07T07:39:50Z ``` -The `package_ecosystem` enum renders as its stored number in table output -(`2` = `ECOSYSTEM_NPM`, `3` = `ECOSYSTEM_PYPI`); use `-o json` for the enum name. +The `package_ecosystem` enum shows its stored number in table and JSON output +(`2` = `ECOSYSTEM_NPM`, `3` = `ECOSYSTEM_PYPI`). In a `WHERE` filter, use the +enum name. @@ -290,7 +295,7 @@ the indexed `item_kind` to find AI-related items: safedep query exec --sql " SELECT inventory_events.item_identity, inventory_events.app, endpoints.identifier FROM inventory_events - JOIN endpoints ON endpoints.id = inventory_events.app + JOIN endpoints ON endpoints.id = inventory_events.invocation_id WHERE inventory_events.item_kind = 'INVENTORY_ITEM_KIND_MCP_SERVER' ORDER BY inventory_events.item_identity" --limit 50 ``` diff --git a/governance/cloud/quickstart.mdx b/governance/cloud/quickstart.mdx index 5239728..64b4114 100644 --- a/governance/cloud/quickstart.mdx +++ b/governance/cloud/quickstart.mdx @@ -14,7 +14,7 @@ SafeDep Cloud aggregates findings from SafeDep tools into a tenant you can query - Complete onboarding and create your tenant. Note the **tenant domain** (for example `your-company.safedep.io`). Tools use it to identify your tenant. + Complete onboarding and create your tenant. Note the **tenant domain** (for example `your-team.your-org.safedep.io`). Tools use it to identify your tenant. diff --git a/governance/cloud/sync.mdx b/governance/cloud/sync.mdx index 9b15ce6..b3bbebd 100644 --- a/governance/cloud/sync.mdx +++ b/governance/cloud/sync.mdx @@ -117,7 +117,7 @@ vet-action sets project identification from the repository: the project name is ### Sync from other CI systems -The pattern is the same on any CI system: provide `SAFEDEP_API_KEY` and `SAFEDEP_TENANT_ID` as environment variables and run `vet scan` with the `--report-sync` flags. See [CI/CD & Platform Integrations](/governance/integrations/overview) for the full GitLab and Bitbucket guides. +The pattern is the same on any CI system: provide `SAFEDEP_API_KEY` and `SAFEDEP_TENANT_ID` as environment variables and run `vet scan` with the `--report-sync` flags. See [CI/CD Integrations](/governance/integrations/overview) for the full GitLab and Bitbucket guides. @@ -249,7 +249,7 @@ Once data lands in your tenant, query it with `safedep query exec` or the web co ## Troubleshooting -Run `vet auth verify` first. For sync errors and missing data, see [Cloud Troubleshooting](/governance/cloud/faq#data-sync-issues). +Run `vet auth verify` first. For sync errors and missing data, see [Data Sync Issues](/governance/cloud/faq#data-sync-issues). For network, tenant domain and CI/CD secret errors, see the other sections of [Cloud Troubleshooting](/governance/cloud/faq). diff --git a/governance/integrations/github.mdx b/governance/integrations/github.mdx index 1892a9f..3849f47 100644 --- a/governance/integrations/github.mdx +++ b/governance/integrations/github.mdx @@ -36,7 +36,7 @@ On every pull request, the app scans updated packages and reports on: When any report fails, the GitHub App **Check** fails and blocks the branch from merging. -The check fails if any _Verified Malicious Package_, _Vulnerability_, or _Risky License_ is found. +With the default policy, the check fails on a _Verified Malicious Package_, a `CRITICAL` or `HIGH` _Vulnerability_, or a _Risky License_. The [cloud policy](#cloud-policy) of a tenant can change the severities and the licenses. ### Cloud Policy diff --git a/governance/shadow-ai-detection.mdx b/governance/shadow-ai-detection.mdx index 9bad223..c1ee0c7 100644 --- a/governance/shadow-ai-detection.mdx +++ b/governance/shadow-ai-detection.mdx @@ -10,7 +10,8 @@ Shadow AI is AI services and SDKs that developers added to the code without a se Coverage tracks the AI ecosystem in current use: -- **Model providers:** OpenAI, Anthropic, Google Gemini, xAI Grok, Mistral, Cohere, Groq, Ollama, AWS Bedrock, Hugging Face, and more +- **Model providers:** OpenAI, Anthropic, Google Gemini, xAI Grok, Mistral, Cohere, Groq, Ollama, AWS Bedrock, Azure OpenAI, Hugging Face, and more +- **AI services:** Azure AI vision and translation - **Frameworks and agent SDKs:** LangChain, LangGraph, LlamaIndex, CrewAI, Vercel AI SDK, OpenAI Agents SDK, Claude Agent SDK, Pydantic AI, Spring AI, Semantic Kernel, and the Model Context Protocol (MCP) SDKs - **Languages:** Python, JavaScript, TypeScript, Java, and Go. Each SDK is covered in the languages it supports. @@ -119,7 +120,7 @@ If you scan vendored dependency source through `--import-dir`, `vet` attempts to { "methods": [{ "technique": "source-code-analysis", "confidence": 1.0 }] } ], "occurrences": [ - { "location": "src/ai.py", "line": 42, "additionalContext": "openai.OpenAI" } + { "location": "src/ai.py", "line": 42, "additionalContext": "openai//OpenAI" } ] }, "properties": [ diff --git a/governance/vet/code-analysis.mdx b/governance/vet/code-analysis.mdx index d8ce731..1046523 100644 --- a/governance/vet/code-analysis.mdx +++ b/governance/vet/code-analysis.mdx @@ -141,7 +141,7 @@ To scan only JavaScript and TypeScript, use `--lang javascript --lang typescript ### Custom Database Locations -Organize databases by project or environment: +Organize databases by project, environment or scope: ```bash # Development environment @@ -149,6 +149,9 @@ vet code scan --app ./src --db ./analysis/dev-code.db # Production analysis vet code scan --app ./dist --db ./analysis/prod-code.db + +# Maven or Gradle layout: production code only, without test code +vet code scan --app src/main --db ./analysis/main-code.db ``` ### Integration with CI/CD diff --git a/package-security/scan/automation.mdx b/package-security/scan/automation.mdx index 4f3f213..1074192 100644 --- a/package-security/scan/automation.mdx +++ b/package-security/scan/automation.mdx @@ -86,13 +86,13 @@ Direct API access uses the same authentication model as the CLI: an `authorizati # Submit a scan curl https://cloud.safedep.io/safedep.services.malysis.v1.PackageScanService/SubmitScan \ -H "authorization: $SAFEDEP_ACCESS_TOKEN" \ - -H "x-tenant-id: your-company.safedep.io" \ + -H "x-tenant-id: your-team.your-org.safedep.io" \ --json '{"target":{"package_version":{"package":{"ecosystem":"ECOSYSTEM_NPM","name":"express"},"version":"4.18.2"}}}' # Poll the scan by id curl https://cloud.safedep.io/safedep.services.malysis.v1.PackageScanService/GetScan \ -H "authorization: $SAFEDEP_ACCESS_TOKEN" \ - -H "x-tenant-id: your-company.safedep.io" \ + -H "x-tenant-id: your-team.your-org.safedep.io" \ --json '{"scan_id":""}' ``` @@ -103,7 +103,7 @@ Direct API access uses the same authentication model as the CLI: an `authorizati BASE = "https://cloud.safedep.io/safedep.services.malysis.v1.PackageScanService" HEADERS = { "authorization": ACCESS_TOKEN, # OAuth2 session access token - "x-tenant-id": "your-company.safedep.io", + "x-tenant-id": "your-team.your-org.safedep.io", } submit = requests.post(f"{BASE}/SubmitScan", headers=HEADERS, json={ diff --git a/reference/api-introduction.mdx b/reference/api-introduction.mdx index 6640779..ed1fc70 100644 --- a/reference/api-introduction.mdx +++ b/reference/api-introduction.mdx @@ -24,7 +24,7 @@ Regardless of transport (gRPC over HTTP/2 or JSON over HTTP/1.1), requests carry | Header | Value | |--------|-------| | `Authorization` | Your API key or JWT, sent **as-is** (no `Bearer` prefix) | -| `X-Tenant-ID` | Your tenant domain (e.g. `your-company.safedep.io`) | +| `X-Tenant-ID` | Your tenant domain (e.g. `your-team.your-org.safedep.io`) | ## OAuth2 / OIDC diff --git a/reference/endpoints.mdx b/reference/endpoints.mdx index ab8254b..0103ffd 100644 --- a/reference/endpoints.mdx +++ b/reference/endpoints.mdx @@ -22,7 +22,7 @@ This list is not a complete egress allowlist. Some integrations reach additional | `mcp.safedep.io` | Hosted [Model Context Protocol](/ai-security/mcp-server) server for AI coding tools | API key | -You create API keys in the web console at [`app.safedep.io/settings/api-keys`](https://app.safedep.io/settings/api-keys). Your **tenant ID** is your tenant domain, for example `your-company.safedep.io`. +You create API keys in the web console at [`app.safedep.io/settings/api-keys`](https://app.safedep.io/settings/api-keys). Your **tenant ID** is your tenant domain, for example `your-team.your-org.safedep.io`. ## Notes diff --git a/reference/sql-query.mdx b/reference/sql-query.mdx index a32e273..67d6ccb 100644 --- a/reference/sql-query.mdx +++ b/reference/sql-query.mdx @@ -22,7 +22,7 @@ Tables come in two kinds: - **Tenant tables** hold *your* data: `projects`, `project_versions`, `boms`, `packages`, `endpoints`, the `component_*` finding tables, and the event tables - (`inventory_events`, `package_guard_events`). + (`inventory_events`, `package_guard_events`, `package_guard_sandbox_violations`). - **Join-only enrichment tables** hold *global* reference data shared across all tenants: `vulnerabilities`, `epss`, `kev`, `licenses`, `malware_analysis`, `open_source_packages`, `open_source_projects`, `scorecards`, @@ -50,7 +50,7 @@ projects -> project_versions -> boms -> packages -> component_vulnerabilities -> | `GROUP BY` | Only columns flagged `groupable`. | | `HAVING` | Filter on aggregates after grouping. | | `ORDER BY` | Including by an aggregate alias. | -| Aggregates | `count`, `sum`, `avg`, `min`, `max`. | +| Aggregates | `count`, `sum`, `avg`, `min`, `max`. `count(*)` is rejected: use `count(column)`. | Every query must filter on an indexed column or a bounded time range. The schema marks which columns are indexed. @@ -101,21 +101,26 @@ JSON shape: "columns": [ { "name": "packages.name", "type": "STRING" } ], "rows": [ { "packages.name": "django" } ], "count": 1, - "next_page_token": "", + "next_page_token": "", + "generated_at": "2026-11-11T10:00:00Z", "stats": { "estimated_cost": 1243.7, "estimated_rows": 1, "elapsed_ms": 9 } } ``` +The JSON has `next_page_token` only when a next page exists. The last page has no token. + ## Pagination Pagination is caller-driven; the CLI does not auto-iterate. Fetch the first page, then re-run the same query with the returned token: ```bash -TOK=$(safedep query exec -o json --sql "SELECT packages.name FROM packages WHERE packages.ecosystem = 'ECOSYSTEM_NPM'" | jq -r .next_page_token) +TOK=$(safedep query exec -o json --sql "SELECT packages.name FROM packages WHERE packages.ecosystem = 'ECOSYSTEM_NPM'" | jq -r '.next_page_token // empty') safedep query exec --sql "SELECT packages.name FROM packages WHERE packages.ecosystem = 'ECOSYSTEM_NPM'" --page-token "$TOK" ``` +If `TOK` is empty, the first page was the last page. + ## Troubleshooting | Error | Cause | Fix | diff --git a/threat-intel/connecting.mdx b/threat-intel/connecting.mdx index 5b642e8..9fe4596 100644 --- a/threat-intel/connecting.mdx +++ b/threat-intel/connecting.mdx @@ -1,7 +1,7 @@ --- title: "Connecting" sidebarTitle: "Authentication & Requests" -description: "Transport, base URL, request headers, authentication, and JSON conventions for the Threat Intel Feed API." +description: "Transport, base URL, request headers, and authentication for the Threat Intel Feed API." --- The feed is a [ConnectRPC](https://connectrpc.com) service. You can call it three ways over one URL: the [**Connect protocol**](https://connectrpc.com/docs/protocol/), **gRPC**, or **gRPC-Web**. This page uses the Connect protocol with JSON, because any HTTP client can send it. For typed stubs in your language, see [SDKs](/threat-intel/sdks). @@ -31,7 +31,7 @@ For example, `.../ThreatIntelService/ListPackageReports`. | Method | `POST` | | `Content-Type` | `application/json` | | `Authorization` | Your API key, sent **as-is**. No `Bearer` prefix. | -| `X-Tenant-ID` | Your tenant domain, for example `your-company.safedep.io`. | +| `X-Tenant-ID` | Your tenant domain, for example `your-team.your-org.safedep.io`. | | Body | The request message as JSON. Use `{}` for an empty message. | Both headers are required on every call. For authentication and authorization failures like `unauthenticated` and `permission_denied`, see [Errors & limits](/threat-intel/errors). @@ -48,7 +48,7 @@ Set these once, then reuse them in every `curl`: ```bash export SAFEDEP_API_KEY="" -export SAFEDEP_TENANT_ID="your-company.safedep.io" +export SAFEDEP_TENANT_ID="your-team.your-org.safedep.io" # Base URL of the service. Append the method name to it. export TI="https://api.safedep.io/safedep.services.threatintel.v1.ThreatIntelService" diff --git a/threat-intel/integrations/jfrog-xray.mdx b/threat-intel/integrations/jfrog-xray.mdx index 9a981d2..22747cc 100644 --- a/threat-intel/integrations/jfrog-xray.mdx +++ b/threat-intel/integrations/jfrog-xray.mdx @@ -30,10 +30,10 @@ To preview the feed without JFrog credentials, run it with [`--dry-run`](#dry-ru ```bash # Option 1: API key login (--api-key is a flag; pass the value with --api-key-value) - safedep auth login --tenant your-tenant.safedep.io --api-key --api-key-value YOUR_API_KEY + safedep auth login --tenant your-team.your-org.safedep.io --api-key --api-key-value YOUR_API_KEY # Option 2: Environment variables (read directly by safedep; no login command needed) - export SAFEDEP_TENANT_ID=your-tenant.safedep.io + export SAFEDEP_TENANT_ID=your-team.your-org.safedep.io export SAFEDEP_API_KEY=YOUR_API_KEY ``` diff --git a/threat-intel/pagination.mdx b/threat-intel/pagination.mdx index d15bca8..1e38dc7 100644 --- a/threat-intel/pagination.mdx +++ b/threat-intel/pagination.mdx @@ -1,6 +1,6 @@ --- title: "Pagination & sync" -sidebarTitle: "Sync a Local Mirror" +sidebarTitle: "Pagination & Sync" description: "Cursor pagination for every list RPC, and the incremental-pull pattern that keeps a local mirror of the Threat Intel Feed in sync." --- diff --git a/threat-intel/quickstart.mdx b/threat-intel/quickstart.mdx index 9f7febe..34c7e27 100644 --- a/threat-intel/quickstart.mdx +++ b/threat-intel/quickstart.mdx @@ -13,7 +13,7 @@ You need three things before your first request: |---|---| | Threat Intel Feed Add-On | Enabled on your account. | | An API key | Your data-plane key, created at [app.safedep.io/settings/api-keys](https://app.safedep.io/settings/api-keys). | -| Your tenant domain | For example `your-company.safedep.io`. | +| Your tenant domain | For example `your-team.your-org.safedep.io`. | ## Run your first query @@ -21,7 +21,7 @@ You need three things before your first request: ```bash export SAFEDEP_API_KEY="" -export SAFEDEP_TENANT_ID="your-company.safedep.io" +export SAFEDEP_TENANT_ID="your-team.your-org.safedep.io" # Base URL of the service. export TI="https://api.safedep.io/safedep.services.threatintel.v1.ThreatIntelService" diff --git a/threat-intel/sdks.mdx b/threat-intel/sdks.mdx index 30c32d8..92dfa57 100644 --- a/threat-intel/sdks.mdx +++ b/threat-intel/sdks.mdx @@ -62,7 +62,7 @@ func main() { client := threatintelv1connect.NewThreatIntelServiceClient( http.DefaultClient, "https://api.safedep.io", - connect.WithInterceptors(auth("", "your-company.safedep.io")), + connect.WithInterceptors(auth("", "your-team.your-org.safedep.io")), ) req := connect.NewRequest(&threatintelv1.ListPackageReportsRequest{ @@ -98,7 +98,7 @@ const transport = createConnectTransport({ interceptors: [ (next) => (req) => { req.header.set("Authorization", ""); - req.header.set("X-Tenant-ID", "your-company.safedep.io"); + req.header.set("X-Tenant-ID", "your-team.your-org.safedep.io"); return next(req); }, ],