# Quickstart

Install dependencies, scan them for malware with vulnetix malscan, read the report, and gate a CI job on it.

You need the Vulnesis CLI on your `PATH` ([installing the CLI](/cli/get-started/install.md)). No sign-in is needed: without credentials the scan runs and reports locally and uploads nothing.

## 1. Install, then scan

malscan reads what is installed, so install first:

```bash
npm ci            # or: pip install -r requirements.txt, bundle install, cargo fetch …
vulnetix malscan
```

The first run downloads the STIX indicator feeds and caches them for an hour. The bad-IP, domain and email blocklists ship embedded in the CLI; to refresh them and the STIX feeds from their sources:

```bash
vulnetix malscan --fetch-definitions
```

## 2. Read the result

The report is organised by package, because the package is what you remove:

```text
 ✖ MALWARE in 1 package          1 malicious · 1 suspicious · 1,246 clean
   npm 612 · go 401 · python 235 packages · 18,402 files · 412,118 known-bad indicators

 MALICIOUS · 1 package · remove it before anything installs again
 ────────────────────────────────────────────────────────────────────────────────────────────────
 ● CRITICAL  npm  event-stream-helper                                                node_modules
             runs code on install       package.json:8   "postinstall": "node lib/setup.js"
             contacts a known-bad host  lib/setup.js:41  fetch('https://cdn-update[.]top/s')
```

| Group | What is in it |
|---|---|
| MALICIOUS | A package with at least one evidence finding. Followed by the steps: remove it, rotate the credentials its install script could read, search logs for the defanged hosts. |
| SUSPICIOUS | A package with only trigger or context findings. Worth a look, not proof. |
| CHECKED | Each install directory, with the packages and files inspected. |
| NOT CHECKED | What was not looked at, and why. |

Indicators are defanged (`cdn-update[.]top`) so a terminal or chat client does not turn them into links. Several rules on one line are one row unless `-v`.

> [!CAREFUL] A scan that checked nothing is not clean
> With no install directories under the path, empty ones, or zero indicators loaded (feeds not fetched), the headline reads `INCOMPLETE` and NOT CHECKED says what to do. The exit code is still `0`. In CI, install dependencies before the scan and check for `INCOMPLETE`.

## 3. Gate CI

`vulnetix malscan` exits `1` whenever a package is malicious, so it is a gate as written:

```yaml
jobs:
  malware:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci --ignore-scripts      # install without running install hooks
      - name: Install the Vulnesis CLI
        run: curl -fsSL https://cli.vulnes.is/install.sh | sh
      - name: Scan installed dependencies
        run: vulnetix malscan --output-file malscan.sarif
```

`--ignore-scripts` keeps a malicious `postinstall` from running before malscan reads it.

Or fold it into the full scan and gate there:

```bash
vulnetix scan --fail-on malware
```

## 4. Look wider

```bash
vulnetix malscan --include-home                  # also ~/.npm, ~/go/pkg/mod, ~/.cargo, ~/.m2 …
sudo vulnetix malscan --include-system           # the whole machine, including /usr/bin and /opt
sudo vulnetix malscan --include-system --system-root /proc/$(pidof myapp)/root   # a running container
```

## Next

- [Detection model](/malware/guides/detection-model.md) to judge a SUSPICIOUS package.
- [Curation and indicators](/malware/guides/curation.md) to report a false positive.
- [Flags](/malware/reference/flags.md) for every option.
