SafeDep Documentation

When SafeDep flags a package as malicious, find the endpoints that tried to install it, the endpoints that installed it, and the projects that depend on it.

This guide needs the SafeDep Cloud Team or Enterprise plan. See pricing.

Prerequisites

PMG syncs to your tenant from developer machines and CI runners. See Package Guard.
Vet scans sync to your tenant. See Cloud Sync.
To run the queries from a terminal, sign in to the safedep CLI. See the SafeDep Cloud Quickstart.

See recent blocks

Open the endpoint list

Show only endpoints with a block

Turn on Has Blocked Events. The Live Activity panel shows recent events, blocks included, and the endpoint of each event.

Open an endpoint

Select the endpoint, then select Package Events. Each blocked package has a Report link to the analysis of the package.

Endpoint list in SafeDep Cloud with the number of blocks on each endpoint and a Live Activity panel of recent events

Find every endpoint that tried to install the package

Select Query in the sidebar and run this query. Replace ECOSYSTEM_PYPI and reqeusts with the ecosystem and the name of the package. The query also finds the installs that a user confirmed after PMG flagged the package.

SELECT endpoints.identifier,
       package_guard_events.package_action,
       package_guard_events.package_version,
       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_CONFIRMED')
  AND package_guard_events.package_ecosystem = 'ECOSYSTEM_PYPI'
  AND package_guard_events.package_name = 'reqeusts'
ORDER BY package_guard_events.timestamp DESC

To run the same query from a terminal, save it as blocked.sql and run safedep query exec --sql-file blocked.sql.

SafeDep Cloud query console with the endpoints that tried to install one package

In the package_action column, 1 is a block and 2 is an install that a user confirmed. PMG records an event when it blocks, holds back, or trusts a package, and when a user confirms the install of a flagged package. It does not record an event for each package that it allows. An install that happened before SafeDep flagged the package does not show here. To find those, check your projects.

Find every project that depends on the package

Filter on the ecosystem, the name, and each malicious version. A name alone also matches safe versions, and packages with the same name in other ecosystems.

SELECT projects.name, packages.name, packages.version
FROM packages
JOIN boms ON boms.id = packages.bom_id
JOIN project_versions ON project_versions.id = boms.project_version_id
JOIN projects ON projects.id = project_versions.project_id
WHERE packages.ecosystem = 'ECOSYSTEM_PYPI'
  AND packages.name = 'reqeusts'
  AND packages.version IN ('2.32.6')

The query returns each project whose latest Vet scan has the package in its dependency tree. For the schema and more examples, see the SQL query guide.

MDM

Find Where a Malicious Package Reached Your Organization

Prerequisites

See recent blocks

Find every endpoint that tried to install the package

Find every project that depends on the package

Next steps

Send Alerts from SafeDep Cloud

Review Package Blocks Across CI Pipelines

​Prerequisites

​See recent blocks

​Find every endpoint that tried to install the package

​Find every project that depends on the package

​Next steps

Send Alerts from SafeDep Cloud

Review Package Blocks Across CI Pipelines

Prerequisites

See recent blocks

Find every endpoint that tried to install the package

Find every project that depends on the package

Next steps