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
20 changes: 20 additions & 0 deletions docs/cmd/policy-edit.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,18 @@ The document of a tenant that has not published a policy yet:
# scan_gate:
# fail_on: high # critical, high, medium, low, info. Now: high (default policy, revision 1)
# fail_on_attacks: fail # report, fail. Now: fail (default policy, revision 1)
# licenses:
# The licenses that fail the gate. A list replaces the list below it. deny: {licenses: []}
# denies nothing. Values: {licenses: [text, ...]}. Now: not set, each tool uses its local
# value
# deny:
# With entries, a license outside the list fails the gate. A list replaces the list below it.
# An empty list turns the allow list off. Values: {licenses: [text, ...]}. Now: not set, each
# tool uses its local value
# allow:
# What the gate does on a package with an unknown license that the lists do not fail. Values:
# allow, report, fail. Now: not set, each tool uses its local value
# unknown: allow
# base_description: Why the base has these values # text

# An example policy override. It applies to the subjects that its selector matches.
Expand Down Expand Up @@ -138,6 +150,14 @@ safedep policy edit --override payments
- The command warns when the file holds a comment that it did not write. The
policy keeps no comments.
- A parent key that you uncomment with no field below it makes no change.
- A license list is one setting. Only a list sets it: `deny: [GPL-3.0-only]`,
or the form that the document writes, `deny: {licenses: [GPL-3.0-only]}`. A list
replaces the list of the layer below. No layer merges two lists.
- `deny: []` or `deny: {licenses: []}` sets a deny list with no entries, so it
denies nothing. `allow: []` turns off the allow list of the layer below.
- A `deny:` or `allow:` key with no list makes no change. This is also true when
you uncomment `deny:` and `licenses:` but leave the items commented, and for
`deny: {}`.
- The command warns when an added or changed policy override selects on a
`managed/`, `reported/` or `scm-property/` label. A tool sets such a label, so
a person on the endpoint can change it. The save continues.
Expand Down
61 changes: 60 additions & 1 deletion docs/cmd/policy-rule-create.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ verified malware.
safedep policy rule create --block PURL [--vers RANGE] --reason TEXT [flags]
safedep policy rule create --block -f FILE --reason TEXT [flags]
safedep policy rule create --trust PURL --scope SCOPE --expires DURATION --reason TEXT [flags]
safedep policy rule create --trust PURL --scope vulnerability --vulnerability ID[:JUSTIFICATION]... --expires DURATION --reason TEXT [flags]
```

## Flags
Expand All @@ -21,7 +22,8 @@ safedep policy rule create --trust PURL --scope SCOPE --expires DURATION --reaso
| `--trust` | Create a trust entry. |
| `-f`, `--file <path>` | With `--block`: a file with one selector on each line, a PURL and an optional range after a space. `#` starts a comment. `-` reads stdin. At most 1,000 selectors, in one revision. |
| `--vers <range>` | A version range, as `'>=1.2.0'` or `'vers:npm/>=1.2.0\|<2.0.0'`. A bare range gets the `vers:` prefix and the type of the PURL. |
| `--scope <scope>` | With `--trust`: `malware`, `cooldown`, `vulnerability` or `all`. Repeatable. Required. |
| `--scope <scope>` | With `--trust`: `malware`, `cooldown`, `vulnerability`, `license` or `all`. Repeatable. Required. |
| `--vulnerability <id>[:<justification>]` | With `--scope vulnerability` as the only scope: waive only this vulnerability id, as `CVE-2024-3094`. Repeatable, or comma-separated. At most 100 ids, each one time. See below. |
| `--expires <when>` | A duration from now, as `30d`, or a date, as `2027-01-26`. Required with `--trust`, and at most 90 days from now for a trust entry. |
| `--reason <text>` | Why the rule exists. Required. Tools show it in a block message. |
| `--ticket <ref>` | A ticket or incident reference, as `IR-2291`. |
Expand All @@ -40,8 +42,41 @@ Selector rules, which the CLI checks before the request:
- A prefix such as `pkg:npm/*` selects every package of an ecosystem. The command
warns, because such a block stops every install of that ecosystem in the tenant.

Trust scopes:

| Scope | Waives |
|-------|--------|
| `malware` | A malware verdict that is not verified. |
| `cooldown` | The dependency cooldown. |
| `vulnerability` | Every vulnerability finding of a scan gate, also one that is published later. With `--vulnerability`, only the named vulnerabilities. |
| `license` | Every license finding of a scan gate: a denied license, a license outside the allow list and an unknown license. |

`--scope all` expands to every trust scope that this CLI knows. The contract has
no "all" value, so a scope that a later release adds never widens a stored entry.
`all` never waives named vulnerabilities, because that scope needs ids.

`--scope vulnerability` with one or more `--vulnerability` flags creates a trust
entry with the one scope `named-vulnerability`. It waives only the vulnerabilities
that it names and their aliases, so a CVE id also waives the GHSA id of the same
vulnerability. A scan gate still fails on every other vulnerability of the
package. The command refuses `--vulnerability` with another scope or with `all`.
`--scope named-vulnerability` is not a value of this command.

Write the id as its advisory publishes it, as `CVE-2024-3094`,
`GHSA-jfh8-c2jp-5v3q` or `RHSA-2024:1234`. The optional justification says why
the vulnerability does not affect the package, with an OpenVEX name:

- `component_not_present`
- `vulnerable_code_not_present`
- `vulnerable_code_not_in_execute_path`
- `vulnerable_code_cannot_be_controlled_by_adversary`
- `inline_mitigations_already_exist`

An id can hold a `:`. The command splits the value at its last `:` only when the
text after it is a justification name, in any case. Otherwise the whole value is
the id, so `RHSA-2024:1234` is one id. A suffix with `_` that is not a name is an
unknown justification. An id that ends with `:` is refused. Without a
justification, `--reason` is the only explanation.

## Examples

Expand Down Expand Up @@ -75,6 +110,30 @@ Applies to every endpoint and project of the tenant (base). Use --override NAME
The rule expires in 30d (2026-11-30)
```

Waive two vulnerabilities of one version, the first with a justification:

```bash
safedep policy rule create --trust pkg:npm/foo@1.2.3 --scope vulnerability \
--vulnerability CVE-2024-1234:vulnerable_code_not_in_execute_path \
--vulnerability GHSA-jfh8-c2jp-5v3q --reason "Not reachable, S-90" --expires 30d
```

```
Applies to every endpoint and project of the tenant (base). Use --override NAME to narrow it.
! This rule loosens the policy: it waives the scan gate findings of CVE-2024-1234, GHSA-jfh8-c2jp-5v3q for pkg:npm/foo@1.2.3.
A scan gate still fails on every other vulnerability of the package.
! Verified malware stays blocked
✓ rule r_5d2 created · revision 50 published
The rule expires in 30d (2026-12-07)
```

Waive the license findings of one version:

```bash
safedep policy rule create --trust pkg:npm/bar@2.0.0 --scope license \
--reason "Legal approved the dual license, LEG-12" --expires 90d
```

Block a list of packages in one revision:

```bash
Expand Down
16 changes: 11 additions & 5 deletions docs/cmd/policy-rule-list.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ safedep policy rule list [--effect trust|block] [--scope SCOPE] [--selector-pref
| Flag | Description |
|------|-------------|
| `--effect <effect>` | `trust` or `block`. |
| `--scope <scope>` | Trust entries with this scope: `malware`, `cooldown` or `vulnerability`. |
| `--scope <scope>` | Trust entries with this scope: `malware`, `cooldown`, `vulnerability`, `license` or `named-vulnerability`. |
| `--selector-prefix <text>` | Rules whose selector starts with this text, as `pkg:npm/`. |
| `--expiring <duration>` | Rules that expire within this time from now, as `7d`. |
| `--override <name>` | Rules that attach to this policy override. |
Expand All @@ -42,10 +42,16 @@ r_80b pkg:npm/leftpad trust malware FP, S-71 web

## Output

`json` holds `rules` (rule id, purl, vers, effect, scopes, reason, ticket,
requester, override id, `attaches_to`, author, added, updated and removed revision, times)
and `next_page_token`. `plain` writes a tab-separated header and one row for each
rule. The table humanizes the expiry.
`json` holds `rules` (rule id, purl, vers, effect, scopes, `vulnerabilities`, reason,
ticket, requester, override id, `attaches_to`, author, added, updated and removed
revision, times) and `next_page_token`. `vulnerabilities` lists each waived `id` and
its `justification` for a trust entry with the scope `named-vulnerability`, and is
an empty list for every other rule. `plain`
writes a tab-separated header and one row for each rule. Its last column,
`vulnerabilities`, has the form of the `--vulnerability` flag, as
`CVE-2024-1234:vulnerable_code_not_in_execute_path,GHSA-jfh8-c2jp-5v3q`, so you
can pass the value back to `--vulnerability`. The table
shows the waived vulnerabilities after the scope, and humanizes the expiry.

## Authentication

Expand Down
35 changes: 24 additions & 11 deletions docs/cmd/policy-rule-show.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,19 +15,32 @@ safedep policy rule show r_9c1
```

```
Rule r_9c1
Selector pkg:npm/evil vers:npm/>=1.2.0
Effect block
Scope -
Reason IR-2291 credential stealer
Ticket IR-2291
Requested by -
Attaches to base
Expires never
Created by carol
Revisions added in revision 48 · active
Rule r_9c1
Selector pkg:npm/evil vers:npm/>=1.2.0
Effect block
Scope -
Vulnerabilities -
Reason IR-2291 credential stealer
Ticket IR-2291
Requested by -
Attaches to base
Expires never
Created by carol
Revisions added in revision 48 · active
```

For a trust entry that waives named vulnerabilities, the `Vulnerabilities` row
shows each id with its justification:

```
Scope named-vulnerability
Vulnerabilities CVE-2024-1234 (vulnerable_code_not_in_execute_path), GHSA-jfh8-c2jp-5v3q
```

`json` holds `rule`, with `vulnerabilities`: an empty list, or each waived `id`
and its `justification`. `plain` writes one tab-separated key and value on each
line. Its `vulnerabilities` value has the form of the `--vulnerability` flag.

After an update of the rule, `Revisions` also names the revision of the last
update, as `added in revision 48, updated in revision 52 · active`.

Expand Down
4 changes: 2 additions & 2 deletions go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@ go 1.26.2

require (
buf.build/gen/go/bufbuild/protovalidate/protocolbuffers/go v1.36.12-20260709200747-435963d16310.1
buf.build/gen/go/safedep/api/grpc/go v1.6.2-20261106062459-79f98cf26185.1
buf.build/gen/go/safedep/api/protocolbuffers/go v1.36.12-20261106062459-79f98cf26185.2
buf.build/gen/go/safedep/api/grpc/go v1.6.2-20261107111754-29a1adb160aa.1
buf.build/gen/go/safedep/api/protocolbuffers/go v1.36.12-20261107111754-29a1adb160aa.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-20261106062459-79f98cf26185.1 h1:S0e3r4qsk7fVC2kEP+WDvLG2s4MmuNWFOMZcsF0mc5s=
buf.build/gen/go/safedep/api/grpc/go v1.6.2-20261106062459-79f98cf26185.1/go.mod h1:C0+UQn8fXxnhC1ifFxYYMFbXoxcS9wmInwIxbApfsx0=
buf.build/gen/go/safedep/api/protocolbuffers/go v1.36.12-20261106062459-79f98cf26185.2 h1:gef9XLbPemfcQJ96qCb0CQPaAXUjX/Jo8iC80gaEOZ0=
buf.build/gen/go/safedep/api/protocolbuffers/go v1.36.12-20261106062459-79f98cf26185.2/go.mod h1:LfbopTmazyAppwhYT2vdRDLDH8ZTm4QNbp9yFjGRbHs=
buf.build/gen/go/safedep/api/grpc/go v1.6.2-20261107111754-29a1adb160aa.1 h1:4uXBhgLhLEn7IOW9avcfYIYKNOI77vOcYm9XQbvfRHo=
buf.build/gen/go/safedep/api/grpc/go v1.6.2-20261107111754-29a1adb160aa.1/go.mod h1:4i7HWcBq17WJ1/i+2RMe/hFwUloX8o4PaviS3I9gd5I=
buf.build/gen/go/safedep/api/protocolbuffers/go v1.36.12-20261107111754-29a1adb160aa.2 h1:1VyJgN+9Z4T+dEVSffnJV/ETVLPsqKkYEvWHguZ/jzc=
buf.build/gen/go/safedep/api/protocolbuffers/go v1.36.12-20261107111754-29a1adb160aa.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
88 changes: 84 additions & 4 deletions internal/cloudpolicy/fields.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,18 +7,26 @@ import (
"strings"
"time"

optionsv1 "buf.build/gen/go/safedep/api/protocolbuffers/go/safedep/policy/options/v1"
specv1 "buf.build/gen/go/safedep/api/protocolbuffers/go/safedep/policy/spec/v1"
"github.com/safedep/dry/tui/humanize"
"google.golang.org/protobuf/proto"
"google.golang.org/protobuf/reflect/protoreflect"
"google.golang.org/protobuf/types/known/durationpb"
"google.golang.org/protobuf/types/known/timestamppb"

"github.com/safedep/cli/internal/duration"
)

// coreCapability is the capability of the package rules. It is not a policy
// setting, so the field lists and the restore leave it out.
const coreCapability = "core"
const (
// coreCapability is the capability of the package rules. It is not a
// policy setting, so the field lists and the restore leave it out.
coreCapability = "core"

// emptyList is the value of a list setting that a layer sets to no
// items. It differs from a setting that the layer does not set.
emptyList = "[]"
)

// FieldValue is one set field of a PolicySpec.
type FieldValue struct {
Expand Down Expand Up @@ -134,11 +142,39 @@ func isLeaf(fd protoreflect.FieldDescriptor) bool {
if fd.Kind() != protoreflect.MessageKind || fd.IsList() || fd.IsMap() {
return true
}
return isFormattedMessage(fd.Message())
return isFormattedMessage(fd.Message()) || isListSetting(fd)
}

// isListSetting reports a message field that the contract marks as one
// setting with a merge option, such as scan_gate.licenses.deny. The message
// wraps one list, so a layer can set the list to no items. Its path is the
// path of the field, and a set wrapper with no items is an empty list, not
// "not set".
func isListSetting(fd protoreflect.FieldDescriptor) bool {
if fd.Kind() != protoreflect.MessageKind || fd.IsList() || fd.IsMap() || isFormattedMessage(fd.Message()) {
return false
}
contract, ok := proto.GetExtension(fd.Options(), optionsv1.E_Field).(*optionsv1.FieldContract)
return ok && contract.GetMerge() != optionsv1.Merge_MERGE_UNSPECIFIED && wrappedList(fd.Message()) != nil
}

// wrappedList is the one repeated field of a list setting, or nil.
func wrappedList(md protoreflect.MessageDescriptor) protoreflect.FieldDescriptor {
if md.Fields().Len() != 1 || !md.Fields().Get(0).IsList() {
return nil
}
return md.Fields().Get(0)
}

func formatFieldValue(fd protoreflect.FieldDescriptor, v protoreflect.Value) (string, string) {
switch {
case isListSetting(fd):
inner := wrappedList(fd.Message())
items := v.Message().Get(inner)
if items.List().Len() == 0 {
return emptyList, emptyList
}
return formatFieldValue(inner, items)
case fd.IsList():
list := v.List()
values := make([]string, 0, list.Len())
Expand Down Expand Up @@ -224,6 +260,15 @@ func FormatJSONValue(path, raw string) (string, string) {
return duration.Format(d), humanDuration(d)
}
return text, text
case fd != nil && (isListSetting(fd) || isWrappedList(path)):
if items, ok := jsonListItems(value, fd); ok {
return items, items
}
compact, err := json.Marshal(value)
if err != nil {
return raw, raw
}
return string(compact), string(compact)
case isString:
return text, text
default:
Expand All @@ -235,6 +280,41 @@ func FormatJSONValue(path, raw string) (string, string) {
}
}

// isWrappedList reports the path of the list inside a list setting, as
// scan_gate.licenses.deny.licenses. A server that walks into the wrapper
// reports a change at this path, so its value reads as the setting's.
func isWrappedList(path string) bool {
i := strings.LastIndex(path, ".")
if i < 0 {
return false
}
parent := fieldByPath(path[:i])
return parent != nil && isListSetting(parent)
}

// jsonListItems reads the items of a list setting from its JSON value: the
// protojson of the wrapper, as {"licenses": ["MIT"]}, or the list itself.
func jsonListItems(value any, fd protoreflect.FieldDescriptor) (string, bool) {
if wrapper, ok := value.(map[string]any); ok && isListSetting(fd) {
value, ok = wrapper[wrappedList(fd.Message()).JSONName()]
if !ok {
value = []any{}
}
}
list, ok := value.([]any)
if !ok {
return "", false
}
if len(list) == 0 {
return emptyList, true
}
items := make([]string, 0, len(list))
for _, item := range list {
items = append(items, fmt.Sprint(item))
}
return strings.Join(items, ", "), true
}

func fieldByPath(path string) protoreflect.FieldDescriptor {
md := (&specv1.PolicySpec{}).ProtoReflect().Descriptor()
var fd protoreflect.FieldDescriptor
Expand Down
25 changes: 25 additions & 0 deletions internal/cloudpolicy/fields_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -18,11 +18,30 @@ func TestFields(t *testing.T) {
assert.Empty(t, Fields(nil))
}

func TestFields_ListSettings(t *testing.T) {
licenses := &scangatev1.LicenseGate{}
deny := &scangatev1.LicenseList{}
deny.SetLicenses([]string{"GPL-3.0-only", "AGPL-3.0-only"})
licenses.SetDeny(deny)
licenses.SetAllow(&scangatev1.LicenseList{})
spec := specWith(scangatev1.Severity_SEVERITY_HIGH, 0)
spec.GetScanGate().SetLicenses(licenses)

assert.Equal(t, []FieldValue{
{Path: "scan_gate.fail_on", Value: "high", Human: "high"},
{Path: "scan_gate.licenses.deny", Value: "GPL-3.0-only, AGPL-3.0-only", Human: "GPL-3.0-only, AGPL-3.0-only"},
{Path: "scan_gate.licenses.allow", Value: "[]", Human: "[]"},
}, Fields(spec))
}

func TestLeafPathsAndCapabilities(t *testing.T) {
paths := LeafPaths()
assert.Contains(t, paths, "scan_gate.fail_on")
assert.Contains(t, paths, "scan_gate.fail_on_attacks")
assert.Contains(t, paths, "package_admission.cooldown.min_age")
assert.Contains(t, paths, "scan_gate.licenses.deny", "a list setting is one setting")
assert.Contains(t, paths, "scan_gate.licenses.unknown")
assert.NotContains(t, paths, "scan_gate.licenses.deny.licenses")
for _, p := range paths {
assert.NotContains(t, p, "core", "package rules are not settings")
}
Expand Down Expand Up @@ -54,6 +73,12 @@ func TestFormatJSONValue(t *testing.T) {
{"package_admission.cooldown.min_age", `"604800s"`, "168h", "7d"},
{"package_admission.cooldown.min_age", `"0s"`, "0s", "0s"},
{"scan_gate.fail_on", "", "-", "-"},
{"scan_gate.licenses.deny", `{"licenses":["GPL-3.0-only","MIT"]}`, "GPL-3.0-only, MIT", "GPL-3.0-only, MIT"},
{"scan_gate.licenses.deny", `{}`, "[]", "[]"},
{"scan_gate.licenses.allow", `["MIT"]`, "MIT", "MIT"},
// A server that walks into the wrapper reports the inner list.
{"scan_gate.licenses.deny.licenses", `["GPL-3.0-only","MIT"]`, "GPL-3.0-only, MIT", "GPL-3.0-only, MIT"},
{"scan_gate.licenses.deny.licenses", `[]`, "[]", "[]"},
{"unknown.path", `"text"`, "text", "text"},
{"unknown.path", `{"a":1}`, `{"a":1}`, `{"a":1}`},
{"unknown.path", `not json`, "not json", "not json"},
Expand Down
Loading
Loading