Skip to content

Document the cloud policy - #118

Merged
KunalSin9h merged 9 commits into
mainfrom
claude/pensive-sagan-3x8any
Nov 5, 2026
Merged

KunalSin9h merged 9 commits into
mainfrom
claude/pensive-sagan-3x8any

Conversation

@abhisek

@abhisek abhisek commented Nov 5, 2026 •

Copy link
Copy Markdown
Member

Summary

This PR adds the docs for SafeDep Cloud Policy, the MVP of cloud policy management (safedep/control-tower#1592, part of safedep/control-tower#1571). A customer on the Team or Enterprise plan can publish a first policy with these docs and the SafeDep CLI alone.

Merge for dogfooding. control-tower and apiguard are deployed with the policy work. The SafeDep team follows these docs for its own tests before the CLI and pmg releases ship. Until then:

Two links point to content that is only on those branches until they merge: the CLI command pages in docs/cmd of safedep/cli, and the cloud.policy section of docs/config.md in safedep/pmg.

No URL changes, so the PR adds no redirects.

Structure

Get Started › Core Concepts › Policy (new nested group)

  • concepts/policy is rewritten with the same URL. It separates the cloud policy (one per tenant, in SafeDep Cloud, enforced by pmg and the pull request checks) from policy as code (vet filter suites with CEL).
  • New pages:
    • concepts/policy-resolution: the default policy, the policy base, policy overrides, and the resolved policy.
    • concepts/labels: labels on endpoints and projects, and selectors.
    • concepts/package-rules: block and trust entries.
    • concepts/policy-revisions: policy changes, the preview, the change direction, notices and rollback.
  • concepts/cel moves into this group with the same URL.

Visibility & Governance › Cloud Policy (new group, after SafeDep Cloud)

  • governance/cloud/policy/overview is the landing page. It lists which tool enforces which setting.
  • The quickstart: publish your first policy.
  • The how-tos:
    • block a package;
    • trust a package;
    • set a cooldown;
    • target a group of endpoints or projects;
    • pull request checks;
    • roll back a change;
    • explain a decision;
    • audit policy changes.
  • governance/cloud/package-exclusions moves into this group with the same URL, under a deprecation warning that points to trust entries (safedep/control-tower#1586).
  • The "Policy & Risk" group goes away. governance/cloud/malware-analysis moves into the SafeDep Cloud group.

Package Security

  • The new page package-security/pmg/cloud-policy covers:
    • the cloud.policy switch and global_lockdown;
    • the fetch every 5 minutes, the cache and the 7-day stale limit;
    • which local settings still apply.
  • dependency-cooldown gets a note that the cloud value can win.
  • Each MDM page gets a shared snippet that tells IT to keep the keys that the cloud manages out of the tool managed file.

Reference › Query & Policy

  • reference/cloud-policy-settings: each setting path, its value in the default policy, and the tool that enforces it. It links to buf.build/safedep/api.
  • reference/cloud-policy-limits: the limits, the retention, the known gaps, and what a holder of the tenant API key can read.
  • policy-as-code and exceptions get one line that separates them from the cloud policy.

Other edits

  • Cloud Policy cards on the governance overview pages.
  • A section on the policy in the GitHub app and Bitbucket app pages.
  • A new placement rule in docs-ia.md, CLAUDE.md and the skill: a policy setting, package rule or policy module goes to Cloud Policy. A tool that enforces the policy goes to that tool's tab. A capability with its own data and workflow, such as a future catalog of approved components, gets its own group.

How the facts were checked

Every command, flag, setting path, default value, limit and behaviour was checked against the source. Nothing comes from the spec or from memory.

Area Source
CLI commands and flags safedep/cli#67
pmg behaviour and settings safedep/pmg#598
Server behaviour control-tower main: services/tenantpolicy, policygate, platform/audit and the glossary
Setting paths and validation the policy contract in safedep/api
Package rule matching policy/match in safedep/dry

The docs follow the code where it differs from the specs:

  • the default policy is at revision 1 and sets no cooldown;
  • pmg fetches the policy every 5 minutes;
  • the first cooldown counts as a change that loosens, and so does a new policy override;
  • the pull request check does not apply the cooldown.

The owner's dogfooding run on 2026-11-05 checked the quickstart flow against production: policy show, edit, publish, a pull request check that failed on a medium vulnerability through a policy override, and the notice email.

Review

A separate review checked more than 40 claims against the source and walked the quickstart as a new Team-plan admin. It found two blocking issues, and a later commit fixes them:

  • pmg config set cloud.policy true prints key not found on a config with no cloud: section. The docs now give the fix: run pmg setup install, or use pmg config edit.
  • A wrong English phrase.

The same commit removes duplicated text, moves CLI detail out of the concept pages, and confirms three claims in the source. The last commit describes the commented fields that safedep policy edit now shows.

Checks

  • bunx -b mintlify broken-links: only the three existing essentials/ failures remain.
  • No em-dashes in the added lines.
  • Every in-page anchor in the changed pages resolves.

Generated by Claude Code

Rewrite concepts/policy to explain the two kinds of policy: the cloud
policy of a tenant and policy as code in a repository. Add four concept
pages for the cloud policy: policy resolution, labels, package rules,
and policy revisions and changes. Put them and concepts/cel in a nested
"Policy" group under Core Concepts. No URL changes.

concepts/policy no longer says that vet-action has a "paranoid" input
or a conventional policy path, because the products map lists neither.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MhRi597EX9odoSDXbVBsxz
Add a "Cloud Policy" group after "SafeDep Cloud", with a landing page,
a quickstart and how-to guides: block a package, trust a package, set a
cooldown, target a group, fail pull request checks, roll back a change,
explain a decision and audit policy changes.

Move governance/cloud/package-exclusions into the new group as its last
page, and add a warning that package rules replace it. Dissolve the
"Policy & Risk" group: governance/cloud/malware-analysis moves into the
"SafeDep Cloud" group. No URL changes.

Add Cloud Policy cards to the Visibility & Governance and SafeDep Cloud
landing pages, and a cloud policy section to the GitHub App and
Bitbucket app pages. The GitHub App page no longer says that the app
enforces policy as code.

In concepts/policy-revisions, state that a setting with no value on one
side of a change counts as a change that loosens, as the change
direction code does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MhRi597EX9odoSDXbVBsxz
Add package-security/pmg/cloud-policy to the Install-Time Package
Blocking group. It tells how to turn on cloud.policy on one machine and
with MDM, what PMG fetches and caches, what PMG does offline or when a
fetch fails, and which PMG settings the cloud policy changes.

Add a note to the dependency cooldown page on when the cloud value wins.
Add a snippet to the MDM overview, Jamf, JumpCloud and Intune pages that
tells IT to set cloud.policy in the managed config and to keep the
cooldown keys out of it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MhRi597EX9odoSDXbVBsxz
Add reference/cloud-policy-settings (each setting, its type, values,
default and enforcing tool, the YAML document and the package rule
fields) and reference/cloud-policy-limits (limits, roles, retention,
API key access and the accepted gaps) to Reference > Query & Policy.

Add a line at the top of reference/policy-as-code and
reference/exceptions that separates them from the cloud policy.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MhRi597EX9odoSDXbVBsxz
docs-ia.md: update the tab table, R4, the placement table and the page
map in section 7. Add three placement rules: a page that changes a cloud
policy setting, package rule or policy module goes to Visibility &
Governance > Cloud Policy; a page that sets up a tool that enforces the
policy goes to the outcome tab of that tool, with a card from Cloud
Policy; an independent capability that the policy only references gets
its own group. The "Policy & Risk" group no longer exists. The total of
section 7 is now counted from docs.json (116 pages); the old total of 89
was stale.

CLAUDE.md and the writing-safedep-docs skill: the same placement rows
and the new list of concepts. products.md: add a Cloud Policy card and
the facts that a review of the source found.

The R4 lines that this change touches use a colon instead of a dash.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MhRi597EX9odoSDXbVBsxz
- Quickstart and the PMG page: tell the user what to do when
  `pmg config set cloud.policy true` prints `key not found`. pmg adds a
  missing template key only when the `cloud` section exists
  (templateScalarDefault in config/yaml_set.go). Otherwise
  `pmg setup install` merges the missing template keys, or the user adds
  the key with `pmg config edit`.
- Trust a package: "no longer applies" replaces "stops to apply".
- A trust entry with the scope `vulnerability` is "Not applicable" in
  PMG on every page.
- One home for duplicated text: the known gaps live in
  reference/cloud-policy-limits, the notice rules in
  concepts/policy-revisions, and the trust scope table in
  reference/cloud-policy-settings. Other pages link to them.
- Concept pages no longer give command procedure: the sync procedure
  moves to target-a-group ("If the publish stops"), the rollback command
  stays in roll-back-a-change, and the --selector syntax moves to
  target-a-group.
- Quickstart: "changes from" replaces "goes from".
- PMG page: the background fetch runs after each command, also a
  blocked one (exit hook in main.go).
- Malicious Package Exclusions: name the Team and Enterprise plans
  (FEATURE_PACKAGE_EXCLUSIONS_MANAGEMENT in billing_tier.go) instead of
  "Pro and above".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MhRi597EX9odoSDXbVBsxz
@abhisek
abhisek marked this pull request as ready for review November 5, 2026 08:34
@safedep

safedep Bot commented Nov 5, 2026 •

Copy link
Copy Markdown

SafeDep Report Summary

Green Malicious Packages Badge Green Vulnerable Packages Badge Green Risky License Badge

No dependency changes detected. Nothing to scan.

View complete scan results →

This report is generated by SafeDep GitHub App

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 5, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-05T08:36:51.819762Z 93cc5d0 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

…kstart

The SafeDep CLI now opens the policy settings document with every field
as a commented line, with its allowed values and its value now. The
quickstart said only that the document opens, so a new admin did not
know how to set a field.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MhRi597EX9odoSDXbVBsxz

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 93cc5d0a07

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread concepts/package-rules.mdx Resolved
The package rules concept said that an old PMG blocks more, never less.
That is true only for trust entries. Such a PMG also gets no block
entries, so a block entry does not stop an install there, and an admin
could count on it during an incident.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MhRi597EX9odoSDXbVBsxz
The filter --applied-revision lists only the endpoints that apply an
older revision. An endpoint that applies no cloud policy reports no
revision, so the filter does not list it. The Policy column shows - for
such an endpoint.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MhRi597EX9odoSDXbVBsxz
@KunalSin9h
KunalSin9h merged commit d1c5b65 into main Nov 5, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants