Metadata-Version: 2.5
Name: cyberxyz-scanner
Version: 1.4.59
Summary: CyberXYZ Vulnerability Scanner CLI — real-time vulnerability intelligence, XYZ scoring, EPSS and depalert scores
Project-URL: Homepage, https://cyberxyz.io
Project-URL: Documentation, https://docs.cyberxyz.io
Author-email: CyberXYZ Security Team <support@cyberxyz.io>
License: Proprietary
License-File: LICENSE
Keywords: CVE,EPSS,GHSA,OSV,scanner,security,vulnerability
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: click>=8.0
Requires-Dist: pip-audit>=2.6
Requires-Dist: pipdeptree>=2.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: requests>=2.28
Requires-Dist: rich>=13.0
Requires-Dist: tabulate>=0.9
Description-Content-Type: text/markdown

# cyberxyz-scanner

CyberXYZ Security CLI. Real-time supply-chain protection for npm, PyPI, Go and .NET (NuGet) on macOS, Linux and Windows.

[![PyPI version](https://img.shields.io/pypi/v/cyberxyz-scanner.svg)](https://pypi.org/project/cyberxyz-scanner/)
[![Python](https://img.shields.io/pypi/pyversions/cyberxyz-scanner.svg)](https://pypi.org/project/cyberxyz-scanner/)
[![License](https://img.shields.io/badge/license-Proprietary-blue.svg)](LICENSE)

The CLI pairs with the CyberXYZ platform to give you per-machine package inventory, proxy
enforcement on every `npm`, `pip`, `go` and `dotnet` install, and CI/CD gating on flagged
dependencies. It is the implementer's interface to a platform that also exposes the same
controls in a web dashboard.

## Install

The package is published on PyPI as `cyberxyz-scanner`. The CLI binary it installs is named
`xyz`.

### With pip

```bash
pip install cyberxyz-scanner
```

### With uv

```bash
uv pip install cyberxyz-scanner
```

Verify the install:

```bash
xyz --help
```

## Quick start (one-time per machine)

```bash
# 1. Sign in with your CyberXYZ email and password. Stores a session in ~/.xyz/config.json
xyz login

# 2. Enroll this machine. One command:
#    - Registers the device with your organization
#    - Points npm (~/.npmrc), pip, Go (GOPROXY) and NuGet at the CyberXYZ proxy,
#      for each one that is installed
#    - Installs the background service for dashboard "Scan now" support
#      (LaunchAgent on macOS, systemd --user on Linux, Task Scheduler on Windows)
xyz proxy setup --machine-name "Alex's MacBook"
```

That's it. Every later install on this device goes through the CyberXYZ proxy: the exact
package version is checked before it downloads, blocked or quarantined packages are
refused with the reason, and the install shows up in your dashboard.

For fleets, skip the interactive login: an org admin creates an enrollment token in the
dashboard (Machines > Enrollment) and MDM runs
`xyz proxy setup --enrollment-token pxe_xyz_...` (or places the token at
`/Library/Application Support/CyberXYZ/enrollment-token`).

For environments that should not run a long-running background process (CI build agents,
sealed builds), pass `--no-install-daemon`.

On company-managed machines, install the agent at system level so developers cannot stop it:

```bash
sudo xyz proxy setup --system          # macOS / Linux
xyz proxy setup --system               # Windows, from an elevated PowerShell
```

This installs a root/SYSTEM service (macOS LaunchDaemon `io.cyberxyz.agent`, Linux
`cyberxyz-agent.service`, Windows scheduled task `CyberXYZAgent`) that starts at boot and
restarts if it is killed. The macOS `.pkg` does the same, and enrolls automatically when MDM
places an enrollment token at `/Library/Application Support/CyberXYZ/enrollment-token`.
Without `--system` (or without admin rights) setup installs the per-user service as before.

## Always-on protection

Every minute the background agent checks what each package manager will actually use,
repairs anything that no longer points at the CyberXYZ proxy, and reports the result to the
dashboard with its heartbeat. Repairs never remove a private or internal registry, and config
files are only written for tools that are installed:

| Tool | What is checked and repaired |
|---|---|
| npm, pnpm | `~/.npmrc` registry + token, pnpm's global rc; as root also `<npm prefix -g>/etc/npmrc` |
| yarn | `~/.yarnrc.yml` `npmRegistryServer` (token scoped to the proxy host under `npmRegistries`) and `registry` in `~/.yarnrc` |
| bun | `~/.bunfig.toml` `[install] registry` |
| pip | user `pip.conf` / `pip.ini`: the proxy is the `index-url`; extra indexes on pypi.org are removed, private indexes are kept; as root also the system file |
| uv | `uv.toml`: the proxy is the default `[[index]]`; pypi.org indexes are removed, private indexes are kept; as root also the system `uv.toml` |
| Go | `GOPROXY=<proxy>,direct` (the proxy refuses blocked modules with 403, so there is no fall-through); `<proxy>` only while the network lock is on; as root also `$GOROOT/go.env` |
| NuGet | `NuGet.Config`: the CyberXYZ source is added and nuget.org sources removed; private feeds are kept |
| Poetry | cannot be forced globally, so it is covered by the network lock only |

The system-level agent does this for every local user account, writing files owned by that
user. The machine token is stored where the agent can always read it
(`/Library/Application Support/CyberXYZ/machine-token`, `/etc/cyberxyz/machine-token`,
`%ProgramData%\CyberXYZ\machine-token`, or `~/.xyz/machine-token` per user), so deleting a
config file only gets it rewritten. Registry overrides in shell startup files
(`NPM_CONFIG_REGISTRY`, `PIP_INDEX_URL`, `GOPROXY=direct`, ...) and in the Windows user
environment are reported, never edited.

**Network lock.** When an org admin turns it on, the system-level agent also maps the public
registries (registry.npmjs.org, registry.yarnpkg.com, registry.npmmirror.com, pypi.org,
files.pythonhosted.org, proxy.golang.org) to `0.0.0.0` in the hosts file, so tools that ignore
config still cannot reach them. NuGet is not locked yet (it relies on config). Edits to the
lock are reverted and reported, and the block is removed when the org turns it off.

`xyz proxy remove` and uninstalling the service are reported to the dashboard before anything
is removed. Under the system service, only an administrator can remove it
(`sudo xyz proxy remove`). `xyz proxy status` shows the per-tool report, the service level and
the network lock state.

### If CyberXYZ is unreachable

The proxy reuses its verdict for any package it checked in the last 24 hours. For anything
else, your org's setting decides: **block** (the default; the developer sees "retry in a
minute") or **allow unchecked**. Org admins change it in Settings > Supply-chain proxy.

## Audit installed packages

Each command below audits the matching ecosystem on this machine, runs the CyberXYZ
watchlist + deep check on suspect packages, and uploads the full inventory to the
platform.

```bash
xyz audit npm                  # local + global node_modules
xyz audit python               # active Python environment via pip
xyz audit go                   # $GOPATH module cache
xyz audit nuget                # packages.lock.json files under cwd
xyz audit                      # npm + python + go back-to-back
```

By default each command uses the watchlist pre-filter for speed (~25-40s on a typical
machine). Pass `--full` to skip the pre-filter and deep-check every package (slower but
covers advisory-only matches at scan time).

## Other useful commands

```bash
# One-off safety check on a single package + version
xyz check axios 1.14.1 -e npm

# CI/CD gate. Non-zero exit on flagged packages.
xyz depalert scan --package-lock package-lock.json --fail-on block
xyz depalert scan --requirements requirements.txt --fail-on quarantine
xyz depalert scan --requirements poetry.lock      # also Pipfile.lock, uv.lock
xyz depalert scan --go-sum go.sum
xyz depalert scan -p axios@1.14.1 -p lodash@4.17.21

# SBOM upload (CycloneDX or SPDX)
xyz inventory upload ./my-app
xyz inventory upload --sbom syft.json

# Diagnostic / housekeeping
xyz --version
xyz proxy status               # proxy config per tool, service level, network lock
xyz proxy whoami               # what (org, machine) does my token resolve to
xyz proxy remove               # restore default registries (reported to your dashboard)
xyz scans list                 # history of recent scans for your org
xyz upgrade                    # pull the latest release from PyPI
```

## CI/CD integrations

Set `XYZ_API_KEY` as a secret and add one of these; any push or PR that pulls in a
malicious or vulnerable package fails the build with a clear reason.

* GitHub Actions: `uses: CyberXYZSecurity/depalert-action@v1` (GitHub Marketplace)
* GitLab CI/CD catalog: `gitlab.com/cyberxyz/depalert`
* Azure DevOps Pipelines: `integrations/azure-pipelines/cyberxyz-supply-chain.yml`
* Or generate one: `xyz ci init`

All of them run the same `xyz depalert scan` engine your laptops use. It reads
`package-lock.json`, `requirements*.txt`, `Pipfile.lock`, `poetry.lock`, `uv.lock` and
`go.sum`.

### `depalert scan` exit codes

| Exit | Meaning |
|---|---|
| 0 | Allowed |
| 1 | Block |
| 2 | Quarantine |
| 3 | Alert |
| 4 | Error, including a manifest that could not be read (it is never treated as clean) |

## Re-enroll, rotate, remove

To rotate the proxy token on a device, re-run `xyz proxy setup --machine-name "..."` as
the same user who enrolled it. The platform replaces the old token and the daemon picks up
the new one at next restart. A machine name registered by another member of your org
can only be re-issued by an org admin; pick a different `--machine-name` otherwise.

To remove a device cleanly, delete it from the dashboard Fleet view. The deletion sweeps
proxy_install_log, proxy_tokens, cli_scans, customer_inventory_uploads,
customer_package_inventory and scan_jobs in one transaction. Re-enroll with the same
command above.

## Platform

* Dashboard: <https://app.cyberxyz.io>
* Documentation: <https://cyberxyz.io>

## License

Proprietary. See [LICENSE](LICENSE).

## Contact

Email: amro@cyberxyz.io
