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

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,7 @@ and drill into package inventory and recent activity.
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
Expand Down Expand Up @@ -150,6 +151,7 @@ Push SafeDep malware findings to external security tools. JFrog XRay is supporte
| [`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 |
Expand Down
128 changes: 128 additions & 0 deletions docs/cmd/policy-decision-list.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
# safedep policy decision list

List the decisions that pmg and the pull request check made with the policy of
the tenant, newest first. Each row says which policy revision and which package
rule or field decided, and where the decision happened. A decision that did not
use the cloud policy is not in the list.

## Synopsis

```
safedep policy decision list [--since DURATION] [--until DURATION]
[--tool pmg|pull-request-check|vet]
[--outcome blocked|failed|allowed]
[--revision N] [--rule RULE_ID] [--override NAME|ID]
[--path PATH] [--package PURL]
[--project PROJECT_ID] [--endpoint ENDPOINT_ID]
[--limit N] [--page-token TOKEN] [--output table|plain|json]
```

## Flags

| Flag | Description |
|------|-------------|
| `--since <duration>` | Only decisions in this time before now, as `7d` or `12h`. |
| `--until <duration>` | Only decisions older than this time before now, as `1d`. It must be shorter than `--since`. |
| `--tool <tool>` | Only decisions of `pmg`, `pull-request-check` or `vet`. |
| `--outcome <outcome>` | Only decisions that `blocked` an install, `failed` a check, or `allowed` a package because a trust entry waived a verdict. |
| `--revision <n>` | Only decisions that applied this tenant policy revision. |
| `--rule <rule-id>` | Only decisions that this package rule made. |
| `--override <name\|id>` | Only decisions that this policy override made: a field that the override set, or a package rule that attaches to it. The command finds the name or the id in the policy at `--revision`, or at head. An override id that the policy does not have, such as the id of a deleted override, goes to the server as is. |
| `--path <path>` | Only decisions that this field made, by its contract path, as `package_admission.cooldown.min_age`. |
| `--package <purl>` | Only decisions about this package, in all its versions. Give a PURL with no version, no qualifiers and no subpath, as `pkg:npm/lodash`. The name must match the stored name exactly, with the same case. See [Package names](#package-names). |
| `--project <id>` | Only decisions at a pull request or a scan of a repository that is bound to this project. |
| `--endpoint <id>` | Only decisions that pmg made on this endpoint. |
| `--limit <n>` | Page size. The server default applies when 0. |
| `--page-token <token>` | Continuation token from a prior response. |

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

The command refuses a value that the server refuses for its length: `--rule`
and `--override` take at most 64 characters, `--path` 256, `--project` 128,
`--endpoint` 100 and the package name 255.

## Package names

The command keeps the name of the PURL as you write it, and writes it in the
form that pmg and vet store:

| Ecosystem | PURL | Name |
|-----------|------|------|
| npm | `pkg:npm/%40acme/ui` | `@acme/ui` |
| Maven | `pkg:maven/org.apache.commons/commons-lang3` | `org.apache.commons:commons-lang3` |
| Go | `pkg:golang/github.com/BurntSushi/toml` | `github.com/BurntSushi/toml` |
| Composer | `pkg:composer/laravel/framework` | `laravel/framework` |
| PyPI | `pkg:pypi/Requests` | `Requests` |

## Columns

| Column | Content |
|--------|---------|
| `WHEN` | When the tool made the decision. |
| `TOOL` | `pmg`, `pull-request-check` or `vet`. |
| `PACKAGE` | The ecosystem, the name and the version. |
| `OUTCOME` | `blocked`, `failed` or `allowed`. |
| `DECIDED BY` | The package rule, or the field path, and the layer or the override that set it: `default policy`, `base` or `override NAME`. |
| `REV` | The tenant policy revision. When the default policy decided, also its revision, as `47 · default 12`. |
| `WHERE` | For pmg, the hostname and the user, and one hint: the CI repository, else the Kubernetes namespace and workload, else the agent. For a check, the repository and the pull request number. For a scan, the repository and the branch or the commit. |
| `LINK` | The check run, the pull request or the CI run. The table has this column only when a row has a link. |

## Examples

The decisions that one package rule made:

```bash
safedep policy decision list --rule r_9c1x4kq7dm
```

```
Policy decisions
WHEN TOOL PACKAGE OUTCOME DECIDED BY REV WHERE LINK
5m ago pmg npm/evil@1.0.0 blocked rule r_9c1x4kq7dm 47 dev-laptop (alice) -
5m ago pull-request-check npm/evil@1.0.1 failed rule r_9c1x4kq7dm 47 acme/payments-api#42 https://github.com/acme/payments-api/runs/7
2 decisions
```

The installs that the cooldown blocked in the last day:

```bash
safedep policy decision list --path package_admission.cooldown.min_age --since 1d
```

```
Policy decisions
WHEN TOOL PACKAGE OUTCOME DECIDED BY REV WHERE
5m ago pmg npm/fresh@0.0.1 blocked package_admission.cooldown.min_age · default policy 47 · default 12 dev-laptop (alice)
1 decision
```

The decisions of a policy override at one revision:

```bash
safedep policy decision list --override payments --revision 47
```

## Output

`json` holds `decisions`, the `PolicyDecision` messages as the server sends them
in protojson with the field names of the contract, and `next_page_token`. Each
message has the full citation (revisions, digest, path, rule id, override id,
layer) and the full decision point, such as the working directory, the CI branch
and commit, the Kubernetes Pod and the agent of a pmg run. `plain` writes a
tab-separated header and one row for each decision, with exact times and ids.

## Permissions

The roles that can read the policy can read the decision log. The tenant needs
policy management.

## Authentication

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

## Exit codes

| Code | Meaning |
|------|---------|
| `0` | The page was read, also when it is empty. |
| non-zero | Validation, authentication or the request failed. |
4 changes: 2 additions & 2 deletions go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@ module github.com/safedep/cli
go 1.26.2

require (
buf.build/gen/go/safedep/api/grpc/go v1.6.2-20261031065119-dc85a10c2beb.1
buf.build/gen/go/safedep/api/protocolbuffers/go v1.36.12-20261031065119-dc85a10c2beb.2
buf.build/gen/go/safedep/api/grpc/go v1.6.2-20261104174030-9113dd6a8ea6.1
buf.build/gen/go/safedep/api/protocolbuffers/go v1.36.12-20261104174030-9113dd6a8ea6.2
github.com/charmbracelet/huh v1.0.0
github.com/charmbracelet/lipgloss v1.1.0
github.com/cli/browser v1.3.0
Expand Down
8 changes: 4 additions & 4 deletions go.sum
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
buf.build/gen/go/bufbuild/protovalidate/protocolbuffers/go v1.36.12-20260709200747-435963d16310.1 h1:6nlcxMOui23ZRVAfJM451duu79P1npA5JRdZqMilrrQ=
buf.build/gen/go/bufbuild/protovalidate/protocolbuffers/go v1.36.12-20260709200747-435963d16310.1/go.mod h1:TCt1lluMFnctISJXvkIQ4x3ABrPuUKCWKyjKdkJNBpw=
buf.build/gen/go/safedep/api/grpc/go v1.6.2-20261031065119-dc85a10c2beb.1 h1:GFuHP+IKmox25L8V2EF4CR3rblReLuKjZCnuOuR7dc4=
buf.build/gen/go/safedep/api/grpc/go v1.6.2-20261031065119-dc85a10c2beb.1/go.mod h1:wVMcwuJdlWZbHcwPPepDJQR1zQDjh/ANlc7Zv0BDfiI=
buf.build/gen/go/safedep/api/protocolbuffers/go v1.36.12-20261031065119-dc85a10c2beb.2 h1:1p9CC/GyQ5POTKPtFvl+48Fk+37rQl/zbAOd1PDDabE=
buf.build/gen/go/safedep/api/protocolbuffers/go v1.36.12-20261031065119-dc85a10c2beb.2/go.mod h1:LfbopTmazyAppwhYT2vdRDLDH8ZTm4QNbp9yFjGRbHs=
buf.build/gen/go/safedep/api/grpc/go v1.6.2-20261104174030-9113dd6a8ea6.1 h1:oKI0awI3q9Ft7eISQzAknDpHx9gDUrFa9Qe4/5+1d+g=
buf.build/gen/go/safedep/api/grpc/go v1.6.2-20261104174030-9113dd6a8ea6.1/go.mod h1:hpgi3VWa8hReWhVtNpPAjWsU4TPf+lYozGgjrHggWhw=
buf.build/gen/go/safedep/api/protocolbuffers/go v1.36.12-20261104174030-9113dd6a8ea6.2 h1:zpGu3bDWbHdBkUgeSt45/O/38JbZMEvn55nEf30u5qg=
buf.build/gen/go/safedep/api/protocolbuffers/go v1.36.12-20261104174030-9113dd6a8ea6.2/go.mod h1:LfbopTmazyAppwhYT2vdRDLDH8ZTm4QNbp9yFjGRbHs=
cloud.google.com/go v0.26.0/go.mod h1:aQUYkXzVsufM+DwF1aE+0xfcU+56JwCaLick0ClmMTw=
github.com/BurntSushi/toml v0.3.1/go.mod h1:xHWCNGjB5oqiDr8zfno3MHue2Ht5sIBksp03qcyfWMU=
github.com/MakeNowJust/heredoc v1.0.0 h1:cXCdzVdstXyiTqTvfqk9SDHpKNjxuom+DOlyEeQ4pzQ=
Expand Down
83 changes: 83 additions & 0 deletions internal/cloudpolicy/mocks/PolicyServiceClient_mock.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

18 changes: 7 additions & 11 deletions internal/cmd/audit/list.go
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,6 @@ package audit

import (
"context"
"errors"
"fmt"
"strings"
"time"
Expand Down Expand Up @@ -95,19 +94,16 @@ func invalidFilter(cause error, help string) error {
func newListRequest(in listInput, now time.Time) (*auditv1.ListAuditEventsRequest, error) {
filters := &auditv1.ListAuditEventsRequest_Filters{}
set := false
if in.Since < 0 || in.Until < 0 {
return nil, invalidFilter(errors.New("--since and --until must not be negative"), "Use a duration such as 7d")
after, before, err := duration.Window(in.Since, in.Until, now, "events")
if err != nil {
return nil, err
}
if in.Since > 0 {
filters.SetOccurredAfter(timestamppb.New(now.Add(-in.Since)))
if after != nil {
filters.SetOccurredAfter(timestamppb.New(*after))
set = true
}
if in.Until > 0 {
if in.Since > 0 && in.Until >= in.Since {
return nil, invalidFilter(errors.New("--until must be shorter than --since"),
"As in --since 7d --until 1d for the events from 7 days ago to 1 day ago")
}
filters.SetOccurredBefore(timestamppb.New(now.Add(-in.Until)))
if before != nil {
filters.SetOccurredBefore(timestamppb.New(*before))
set = true
}
if in.Action != "" {
Expand Down
15 changes: 12 additions & 3 deletions internal/cmd/policy/cmd.go
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
// Package policy registers the `safedep policy` command tree, the CLI for
// policy management in SafeDep Cloud: the policy settings document, policy
// changes, policy revisions and package rules. Every verb needs control
// plane credentials.
// changes, policy revisions, package rules and the decision log. Every
// verb needs control plane credentials.
package policy

import (
Expand Down Expand Up @@ -54,6 +54,15 @@ func Register(root *cobra.Command, a *app.App) {
}
rule.AddCommand(ruleCreateCmd(a), ruleListCmd(a), ruleShowCmd(a), ruleUpdateCmd(a), ruleDeleteCmd(a))

parent.AddCommand(change, revision, rule)
decision := &cobra.Command{
Use: "decision",
Short: "Read the decisions that the policy made",
Long: "Read the decision log: the decisions that pmg and the pull request check made with the policy " +
"of the tenant. Each decision cites the policy revision and the rule or field that decided, and " +
"says where it happened. The roles that can read the policy can read the decision log.",
}
decision.AddCommand(decisionListCmd(a))

parent.AddCommand(change, revision, rule, decision)
root.AddCommand(parent)
}
Loading
Loading