Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
de96147
feat(policy): add safedep policy commands for cloud policy management
claude Oct 31, 2026
c846b5f
feat(project,endpoint,audit): add label, policy and audit commands
claude Oct 31, 2026
4e649b1
fix(policy): keep override ids, guard edits, confirm loosening publishes
claude Oct 31, 2026
939daf5
fix(policy): use one policy snapshot for rule list, keep fractional t…
claude Oct 31, 2026
9429773
ci: skip the PMG cooldown for the SafeDep API SDK and dry
claude Oct 31, 2026
18da4bb
chore(deps): bump the SafeDep API SDK for ListPolicyDecisions
claude Nov 4, 2026
233f92b
refactor(duration): share the --since and --until time window
claude Nov 4, 2026
6c6959c
feat(policy): add safedep policy decision list
claude Nov 4, 2026
ddaa59a
fix(policy): accept a deleted override id, keep package names, check …
claude Nov 4, 2026
ff6bc18
docs(cmd): show only labels, warnings and default policy values that …
claude Nov 5, 2026
53bec64
docs(cmd): match change directions and policy reports to the server
claude Nov 5, 2026
e370e10
feat(policy): show every settings field in the policy edit document
claude Nov 5, 2026
6d8f6fa
fix(policy): make the edit template safe to clear and honest in its n…
claude Nov 5, 2026
5ccf75e
docs: write the help, warnings and errors of the policy commands in STE
claude Nov 5, 2026
13db8a6
fix(policy): name each override change in a plain sentence
claude Nov 5, 2026
5659676
fix(policy): fix the findings of a review against a live tenant
claude Nov 5, 2026
3727038
fix(policy): save a new title of a change when the settings do not ch…
claude Nov 5, 2026
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
19 changes: 19 additions & 0 deletions .github/pmg/config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# PMG settings for the CI jobs of this repository. ci.yml and goreleaser.yml
# pass this file to safedep/pmg as config-file. PMG reads the keys that this
# file does not set from its own template.
dependency_cooldown:
enabled: true
days: 2
# SafeDep publishes these modules. The SDK bump takes the build that BSR
# makes right after an API merge, and the cooldown would block that build.
# PMG still runs malware analysis on them. control-tower and malysis skip
# the same modules.
skip:
- purl: pkg:golang/buf.build/gen/go/safedep/api/connectrpc/go
reason: "SafeDep API SDK, generated by BSR"
- purl: pkg:golang/buf.build/gen/go/safedep/api/grpc/go
reason: "SafeDep API SDK, generated by BSR"
- purl: pkg:golang/buf.build/gen/go/safedep/api/protocolbuffers/go
reason: "SafeDep API SDK, generated by BSR"
- purl: pkg:golang/github.com/safedep/dry
reason: "SafeDep shared library"
2 changes: 2 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,8 @@ jobs:
api-key: ${{ secrets.SAFEDEP_CLOUD_API_KEY }}
tenant-id: ${{ secrets.SAFEDEP_CLOUD_TENANT_DOMAIN }}
endpoint-id: CICD_GHA_SAFEDEP_CLI
# The cooldown and its skip list. The path is relative to the checkout.
config-file: .github/pmg/config.yml

- name: Install dependencies
run: pnpm install --frozen-lockfile
Expand Down
2 changes: 2 additions & 0 deletions .github/workflows/goreleaser.yml
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,8 @@ jobs:
api-key: ${{ secrets.SAFEDEP_CLOUD_API_KEY }}
tenant-id: ${{ secrets.SAFEDEP_CLOUD_TENANT_DOMAIN }}
endpoint-id: CICD_GHA_SAFEDEP_CLI
# The cooldown and its skip list. The path is relative to the checkout.
config-file: .github/pmg/config.yml

- name: Install dependencies
run: pnpm install --frozen-lockfile
Expand Down
11 changes: 11 additions & 0 deletions .mockery.yml
Original file line number Diff line number Diff line change
Expand Up @@ -10,3 +10,14 @@ packages:
filename: "{{.InterfaceName}}_mock.go"
interfaces:
CredentialStore:
buf.build/gen/go/safedep/api/grpc/go/safedep/services/controltower/policy/v1/policyv1grpc:
config:
# The gRPC clients are generated code, which mockery skips by default.
include-auto-generated: true
dir: "internal/cloudpolicy/mocks"
pkgname: "mocks"
structname: "{{.InterfaceName}}Mock"
filename: "{{.InterfaceName}}_mock.go"
interfaces:
PolicyServiceClient:
LabelServiceClient:
40 changes: 40 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,19 @@ Log in to SafeDep Cloud, manage credential profiles, and switch between tenants.
Monitor the health of every endpoint reporting to your tenant, list active machines,
and drill into package inventory and recent activity.

**Policy management**: `safedep policy`
Edit the one policy of your tenant: the policy base, policy overrides that select
endpoints and projects by label, and package rules that trust or block packages.
Review each policy change before you publish it, and roll back from any policy revision.
See which rule made each decision of pmg and the pull request check, and where.

**Projects and labels**: `safedep project`
List projects by label selector, set `custom/` labels, and see which policy applies
to a project and why.

**Audit log**: `safedep audit`
See who changed the policy, what, and when.

**Security telemetry queries**: `safedep query`
Run SQL against SafeDep Cloud's query service. Inspect packages, events, and findings
across your entire fleet.
Expand Down Expand Up @@ -118,11 +131,38 @@ Push SafeDep malware findings to external security tools. JFrog XRay is supporte
| [`safedep endpoint show`](./docs/cmd/endpoint-show.md) | Show endpoint detail |
| [`safedep endpoint activity list`](./docs/cmd/endpoint-activity-list.md) | List recent endpoint activity |
| [`safedep endpoint inventory list`](./docs/cmd/endpoint-inventory-list.md) | List current endpoint inventory |
| [`safedep endpoint label set`](./docs/cmd/endpoint-label-set.md) | Set custom labels on endpoints |
| [`safedep endpoint label delete`](./docs/cmd/endpoint-label-delete.md) | Delete custom labels from endpoints |
| [`safedep endpoint policy show`](./docs/cmd/endpoint-policy-show.md) | Show the policy of an endpoint and the source of each value |
| [`safedep policy show`](./docs/cmd/policy-show.md) | Show a summary of the tenant policy |
| [`safedep policy get`](./docs/cmd/policy-get.md) | Write the policy settings document as YAML |
| [`safedep policy edit`](./docs/cmd/policy-edit.md) | Edit the policy settings document in your editor |
| [`safedep policy change list`](./docs/cmd/policy-change-list.md) | List policy changes |
| [`safedep policy change show`](./docs/cmd/policy-change-show.md) | Show what a policy change does |
| [`safedep policy change edit`](./docs/cmd/policy-change-edit.md) | Edit the policy settings of an open policy change |
| [`safedep policy change sync`](./docs/cmd/policy-change-sync.md) | Move the base of a policy change to the head revision |
| [`safedep policy change publish`](./docs/cmd/policy-change-publish.md) | Publish a policy change as a new policy revision |
| [`safedep policy change delete`](./docs/cmd/policy-change-delete.md) | Delete an open policy change |
| [`safedep policy change create`](./docs/cmd/policy-change-create.md) | Create a policy change that restores an old revision |
| [`safedep policy revision list`](./docs/cmd/policy-revision-list.md) | List policy revisions |
| [`safedep policy revision show`](./docs/cmd/policy-revision-show.md) | Show one policy revision with its policy settings |
| [`safedep policy rule create`](./docs/cmd/policy-rule-create.md) | Create a trust entry or block entries |
| [`safedep policy rule list`](./docs/cmd/policy-rule-list.md) | List package rules |
| [`safedep policy rule show`](./docs/cmd/policy-rule-show.md) | Show one package rule |
| [`safedep policy rule update`](./docs/cmd/policy-rule-update.md) | Change the reason, expiry, ticket or requester of a package rule |
| [`safedep policy rule delete`](./docs/cmd/policy-rule-delete.md) | Delete a package rule |
| [`safedep policy decision list`](./docs/cmd/policy-decision-list.md) | List the decisions that the policy made, and where |
| [`safedep audit event list`](./docs/cmd/audit-event-list.md) | List audit events of the tenant |
| [`safedep query exec`](./docs/cmd/query-exec.md) | Execute a SQL query against SafeDep Cloud |
| [`safedep query schema list`](./docs/cmd/query-schema-list.md) | List tables in the query schema |
| [`safedep query schema show`](./docs/cmd/query-schema-show.md) | Show one table from the query schema |
| [`safedep query schema get`](./docs/cmd/query-schema-get.md) | Get the full schema in one call (for AI agents and scripts) |
| [`safedep project sync`](./docs/cmd/project-sync.md) | Sync GitHub or Bitbucket repositories into SafeDep projects |
| [`safedep project list`](./docs/cmd/project-list.md) | List projects with their labels |
| [`safedep project show`](./docs/cmd/project-show.md) | Show one project with its labels and policy |
| [`safedep project label set`](./docs/cmd/project-label-set.md) | Set custom labels on projects |
| [`safedep project label delete`](./docs/cmd/project-label-delete.md) | Delete custom labels from projects |
| [`safedep project policy show`](./docs/cmd/project-policy-show.md) | Show the policy of a project and the source of each value |
| [`safedep project scan create`](./docs/cmd/project-scan-create.md) | Submit project scans by name to SafeDep Cloud-hosted scanners |
| [`safedep project scan list`](./docs/cmd/project-scan-list.md) | List project scans with filters |
| [`safedep package scan run`](./docs/cmd/package-scan-run.md) | Submit a package for on-demand scanning |
Expand Down
64 changes: 64 additions & 0 deletions docs/cmd/audit-event-list.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
# safedep audit event list

List the audit events of the tenant, newest first. Each admin action, such as a
policy publish or a label change, writes one audit event.

## Synopsis

```
safedep audit event list [--since DURATION] [--until DURATION] [--action PREFIX]
[--resource KIND[/ID]] [--actor ACTOR]
[--limit N] [--page-token TOKEN] [--output table|plain|json]
```

## Flags

| Flag | Description |
|------|-------------|
| `--since <duration>` | Only events in this time before now, as `7d` or `12h`. |
| `--until <duration>` | Only events older than this time before now, as `1d`. It must be shorter than `--since`. |
| `--action <prefix>` | Only events whose action starts with this text. `policy.` lists every policy action, and `policy.rule.` lists the package rule actions. |
| `--resource <kind[/id]>` | Only events about a resource kind, or one resource. The kinds are `policy_change`, `package_rule`, `endpoint` and `project`, as in `--resource package_rule` or `--resource policy_change/18`. |
| `--actor <actor>` | Only events of this actor. The server matches the actor id or the display name exactly. |
| `--limit <n>` | Page size. The server default applies when 0. |
| `--page-token <token>` | Continuation token from a prior response. |

Actions have the form `<domain>.<resource>.<verb>`, as `policy.change.publish`.
To list the policy events, use `--action policy.`. `--resource` takes a resource
kind, not a domain.

## Examples

```bash
safedep audit event list --since 7d --action policy.
```

```
Audit events
WHEN ACTOR ACTION RESOURCE RESULT DETAIL
10m ago alice policy.rule.delete package_rule r_80b success revision=51
12m ago alice policy.rule.update package_rule r_77e success revision=50
2d ago alice policy.change.publish policy_change 18 success revision=47
3 events
```

## Output

`json` holds `events` (event id, actor, actor kind, action, resource kind and id,
result, details, request id, time) and `next_page_token`. `plain` writes a
tab-separated header and one row for each event.

## Permissions

Reading the audit log needs the Admin role.

## Authentication

Requires a control-plane OAuth session. Run `safedep auth login` first.

## Exit codes

| Code | Meaning |
|------|---------|
| `0` | The page was read. |
| non-zero | Validation, authentication or the request failed. |
2 changes: 1 addition & 1 deletion docs/cmd/endpoint-activity-list.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ Guard events carry one of the following actions:
| Flag | Default | Description |
|------|---------|-------------|
| `--type` | `guard` | Activity type: `all`, `guard`, or `inventory` |
| `--since` | `168h` | Trailing time window length, e.g. `24h`, `168h`, `30m` |
| `--since` | `168h` | Trailing time window length, as `7d`, `24h` or `30m` |
| `--endpoint` | _(none)_ | Filter by endpoint ULID or cached hostname; repeatable |
| `--action` | `blocked,cooldown-blocked` (when type includes guard) | Package action filter for guard events: `blocked`, `confirmed`, `trusted`, `cooldown-blocked`; repeatable |
| `--tool` | _(none)_ | Client-side filter by tool name (e.g. `claude-code`) |
Expand Down
2 changes: 1 addition & 1 deletion docs/cmd/endpoint-inventory-list.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ By default, dedupe is performed over the fetched page only. For a complete snaps

| Flag | Default | Description |
|------|---------|-------------|
| `--since` | `168h` | Trailing time window length, e.g. `24h`, `168h`, `30m` |
| `--since` | `168h` | Trailing time window length, as `7d`, `24h` or `30m` |
| `--endpoint` | _(none)_ | Filter by endpoint ULID or cached hostname; repeatable |
| `--kind` | _(none)_ | Filter by inventory kind (see Kind vocabulary below); repeatable |
| `--scope` | _(none)_ | Filter by scope: `system` or `project` |
Expand Down
33 changes: 33 additions & 0 deletions docs/cmd/endpoint-label-delete.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# safedep endpoint label delete

Delete `custom/` labels from endpoints. The change takes effect at the next
policy fetch of each endpoint.

## Synopsis

```
safedep endpoint label delete ENDPOINT... --key custom/KEY...
```

## Flags

| Flag | Description |
|------|-------------|
| `--key <custom/key>` | A label key. Repeatable, up to 32. |

## Examples

```bash
safedep endpoint label delete arjuns-mbp --key custom/team
```

## Authentication

Requires a control-plane OAuth session. Run `safedep auth login` first.

## Exit codes

| Code | Meaning |
|------|---------|
| `0` | The labels were deleted. |
| non-zero | Validation, endpoint resolution or the request failed. |
45 changes: 45 additions & 0 deletions docs/cmd/endpoint-label-set.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
# safedep endpoint label set

Set `custom/` labels on endpoints. A policy override selects endpoints by their
labels. The label takes effect at the next policy fetch of each endpoint.

## Synopsis

```
safedep endpoint label set ENDPOINT... --label custom/KEY=VALUE...
```

## Flags

| Flag | Description |
|------|-------------|
| `--label <custom/key=value>` | A label. Repeatable, up to 32. |

An endpoint is a ULID, a unique ULID prefix, or a hostname that
`safedep endpoint list` cached. Give up to 100 endpoints. An admin writes only
`custom/` labels. pmg reports the `reported/os` and `reported/arch` labels, as
`reported/os=darwin`. No tool sends `managed/` labels in this release.

Until endpoint enrollment ships, an endpoint label is not an access boundary.
Select on `custom/` labels for a policy override that loosens the policy.

## Examples

```bash
safedep endpoint label set arjuns-mbp --label custom/team=release
```

```
✓ label set on 1 endpoint. It takes effect at the next policy fetch of each endpoint
```

## Authentication

Requires a control-plane OAuth session. Run `safedep auth login` first.

## Exit codes

| Code | Meaning |
|------|---------|
| `0` | The labels were set. |
| non-zero | Validation, endpoint resolution or the request failed. |
19 changes: 16 additions & 3 deletions docs/cmd/endpoint-list.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# safedep endpoint list

List endpoints reporting to SafeDep Cloud, with optional filters for capability, blocked installs, silent duration, and identity search.
List the endpoints that report to SafeDep Cloud, with filters for capability, blocked installs, silent duration, identity search, labels and the applied policy revision.

## Synopsis

Expand All @@ -12,18 +12,31 @@ safedep endpoint list [flags] [--output table|plain|json] [--profile <name>]

| Flag | Description |
|---|---|
| `--since <duration>` | Trailing window length for event counts (default `24h`). Accepts Go duration strings: `24h`, `168h`, `30m`. |
| `--since <duration>` | Trailing window length for event counts (default `168h`, 7 days). Accepts a number and a unit, as `7d`, `24h` or `30m`. |
| `--capability <name>` | Filter to endpoints that advertise this capability. Repeatable. Accepted values: `guard`, `tracer`, `advisor`, `inventory`. |
| `--blocked` | Only endpoints with at least one blocked package-guard install in the window. |
| `--silent-for <duration>` | Only endpoints whose last sync is older than this duration (client-side filter; best-effort within `--limit`). |
| `--silent-for <duration>` | Only endpoints whose last sync is older than this duration, as `7d` (client-side filter, best-effort within `--limit`). |
| `--search <substring>` | Case-insensitive substring match on hostname or name (client-side filter; best-effort within `--limit`). |
| `--selector <selector>` | Only endpoints whose labels match this label selector, as `reported/os=darwin,custom/team=release`. The syntax is the one of [`safedep project list`](./project-list.md). |
| `--applied-revision '<N'` | Only endpoints where a tool applies a policy revision lower than `N`, as `'<48'`. Quote the value, because the shell reads `<`. |
| `--limit <n>` | Page size. Server default applies when `0` (the default). |
| `--page-token <token>` | Continuation token from a prior response, to fetch the following page. |

Inherits root flags `--output` and `--profile`.

## Examples

Find the endpoints that have not applied policy revision 48 yet:

```bash
safedep endpoint list --applied-revision '<48'
```

The `Policy` column shows the applied policy revision that each tool reported:
`rev 48` when every tool applies the same revision, or `pmg 48, vet 47`. JSON
output carries `tool_policies` for each endpoint: the tool, its version, its
applied policy revision and the state of the policy in the tool.

List all endpoints active in the last 24 hours (default window):

```bash
Expand Down
52 changes: 52 additions & 0 deletions docs/cmd/endpoint-policy-show.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# safedep endpoint policy show

Show the intended policy of one endpoint: each field, its value, and its source.
The output also shows the policy that each tool applied, as the tool reported it
at its last check-in, and the fields that the tool did not apply as the policy
says.

## Synopsis

```
safedep endpoint policy show ENDPOINT [--field PATH]... [--output table|plain|json]
```

## Flags

| Flag | Description |
|------|-------------|
| `--field <path>` | Show only this contract path, or the paths below it. Repeatable. |

## Examples

```bash
safedep endpoint policy show arjuns-mbp --field package_admission.cooldown.min_age
```

```
Endpoint arjuns-mbp (01KR0EKN6PMW0ZRFRN992H1PKX)
Policy revision 52 · overrides laptops (100)
Default policy revision 1
Package rules 211 (184 trust, 27 block)

FIELD VALUE SOURCE EXCEPTIONS
package_admission.cooldown.min_age 5d override "laptops" (100) -

Applied policy, as each tool reported it
TOOL VERSION REVISION STATE FETCHED REPORTED
pmg 2.3.1 52 applied 3m ago 3m ago
```

The output format is the same as for
[`safedep project policy show`](./project-policy-show.md).

## Authentication

Requires a control-plane OAuth session. Run `safedep auth login` first.

## Exit codes

| Code | Meaning |
|------|---------|
| `0` | The policy was read. |
| non-zero | Validation, endpoint resolution or the request failed. |
2 changes: 1 addition & 1 deletion docs/cmd/endpoint-show.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ The `<endpoint>` argument is resolved as follows: if it is a ULID it is used dir

| Flag | Default | Description |
|------|---------|-------------|
| `--since DURATION` | `168h` | Trailing window length used for per-tool event volumes and recent block lookup. Accepts Go duration strings, e.g. `24h`, `168h`, `720h`. |
| `--since DURATION` | `168h` | Trailing window length used for per-tool event volumes and recent block lookup. Accepts a number and a unit, as `7d`, `24h` or `30d`. |

## Examples

Expand Down
2 changes: 1 addition & 1 deletion docs/cmd/endpoint-status.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ The response includes total registered endpoints, those that have synced at leas

| Flag | Default | Description |
|---|---|---|
| `--since` | `24h` | Trailing window length parsed as a Go duration string (e.g. `24h`, `168h`, `30m`). A non-positive value lets the server apply its own default window. |
| `--since` | `168h` | Trailing window length, a number and a unit, as `7d`, `24h` or `30m`. A non-positive value lets the server apply its own default window. |
| `--output` | `table` | Output format: `table`, `plain`, or `json`. Inherited from the root command. |
| `--profile` | `default` | Credential profile to use. Inherited from the root command. |
| `--insecure-keychain-fallback` | `false` | Allow falling back to an unencrypted credential store. Inherited from the root command. |
Expand Down
Loading
Loading