> ## Documentation Index
> Fetch the complete documentation index at: https://docs.safedep.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Malware Analysis

> Detect malicious packages in your dependencies by querying SafeDep's known malicious packages database

> [!NOTE]
>
> Malware analysis is available for free. No API key is required to query SafeDep's known malicious packages database. See [pricing](https://safedep.io/pricing) for SafeDep Cloud features.

Check your open source dependencies against SafeDep's continuously updated database of known malicious packages using [Vet](https://github.com/safedep/vet). Vet queries SafeDep's threat intelligence service, which is populated through continuous static and dynamic analysis of packages from public registries.

> [!NOTE]
>
> This page covers the **fast path**: a free lookup against SafeDep's database of known malicious packages, built into Vet, PMG, and the SafeDep MCP server. It answers in milliseconds but only covers packages SafeDep has already analyzed. To run a **new analysis** of a specific component (any package version, an IDE extension, or a GitHub repository), use [On-Demand Package Scanning](https://docs.safedep.io/package-security/scan/overview), an independent paid feature. Vet itself no longer submits packages for analysis. On-demand scanning moved to `safedep package scan`.

## Supported Ecosystems

> [card] npm
>
> JavaScript and TypeScript packages

> [card] PyPI
>
> Python packages and wheels

> [card] Go Modules
>
> Go language modules

> [card] RubyGems
>
> Ruby packages and gems

> [card] GitHub Actions
>
> GitHub Action workflows

> [card] VS Code Extensions
>
> Visual Studio Code extensions

## Requirements

Install the latest version of [Vet](https://github.com/safedep/vet/#installation).

> [!NOTE]
>
> No API key is required. Querying known malicious packages works out of the box, with no SafeDep Cloud onboarding. A SafeDep Cloud account is optional and enables cloud features such as report sync and higher rate limits. See the [SafeDep Cloud Quickstart](https://docs.safedep.io/governance/cloud/quickstart.md).

## Repository Scanning

### Basic Malware Scanning

Enable malware analysis with the `--malware-query` flag:

```bash theme={null}
vet scan -D /path/to/code --malware-query
```

Because Vet performs a lookup against known malicious packages, results are returned quickly, which works well for pull requests and CI/CD pipelines.

> [!NOTE]
>
> The `--malware` flag is a deprecated alias for `--malware-query` and behaves identically. It will be removed in a future release.

### Specific Manifest Scanning

Scan individual package manifest files:

```bash theme={null}
# npm projects
vet scan -M package-lock.json --malware-query

# Python projects
vet scan -M requirements.txt --malware-query

# Go projects
vet scan -M go.mod --malware-query

# Ruby projects
vet scan -M Gemfile.lock --malware-query
```

### PURL-Based Scanning

Scan specific packages using Package URLs:

```bash theme={null}
vet scan --purl pkg:npm/llm-oracle@1.0.2 --malware-query
```

![Malware analysis results for llm-oracle package](https://mintcdn.com/safedep/A0tSXvZ_XcagO9QB/images/vet-malysis-llm-oracle.png?fit=max\&auto=format\&n=A0tSXvZ_XcagO9QB\&q=85\&s=d82d51432119f69fb9fb2636ef3dfe82)

## Visual Studio Code Extensions

Scan locally installed VS Code extensions:

```bash theme={null}
vet scan --vsx --malware-query
```

> [!WARNING]
>
> VS Code extension scanning is supported only for local developer machines, not in CI/CD environments.

## GitHub Actions Integration

### vet-action

Enable malicious package protection in GitHub repositories using [vet-action](https://github.com/safedep/vet-action):

```yaml theme={null}
name: Malware Protection
on:
  pull_request:
    branches: [ main ]

jobs:
  malware-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run malware analysis
        uses: safedep/vet-action@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

> [!NOTE]
>
> Known malicious package detection does not require an API key. SafeDep Cloud configuration (`cloud`, `cloud-key`, `cloud-tenant`) is optional and only enables cloud reporting and sync. See the [vet-action documentation](https://github.com/safedep/vet-action?tab=readme-ov-file#cloud-mode) for cloud mode.

### Pull Request Integration

When enabled, Vet scans changed packages for malware and provides results directly in pull requests:

![vet malware analysis in GitHub PR](https://mintcdn.com/safedep/A0tSXvZ_XcagO9QB/images/vet-action-malysis-1.png?fit=max\&auto=format\&n=A0tSXvZ_XcagO9QB\&q=85\&s=65d9f9ce9240be1b2cc35b7c04871a2c)

Expand comments to view detailed package analysis results:

![Detailed malware analysis results in PR](https://mintcdn.com/safedep/A0tSXvZ_XcagO9QB/images/vet-action-malysis-2.png?fit=max\&auto=format\&n=A0tSXvZ_XcagO9QB\&q=85\&s=19a909b404c9eaf7fb33e8f021714f60)

## Understanding Results

### Classification Levels

* **SAFE**: No malicious behavior detected
* **SUSPICIOUS**: Potentially risky patterns identified
* **MALICIOUS**: Confirmed malicious behavior found

### How Packages Are Analyzed

SafeDep continuously analyzes packages from public registries and records the results in its known malicious packages database. Vet queries this database during a scan. The analysis behind these records combines:

> [accordion] Static Analysis
>
> * Code pattern analysis
> * Suspicious function detection
> * Obfuscation identification

> [accordion] Behavioral Analysis
>
> * Network communication patterns
> * File system access patterns
> * Process execution analysis

> [accordion] Metadata Analysis
>
> * Package metadata anomalies
> * Publisher reputation analysis
> * Distribution pattern analysis

## CI/CD Integration Examples

### GitLab CI

```yaml theme={null}
stages:
  - security

malware-scan:
  stage: security
  image: ghcr.io/safedep/vet:latest
  script:
    - vet scan -D . --malware-query --report-json malware-report.json
  artifacts:
    reports:
      security: malware-report.json
```

### Jenkins Pipeline

```groovy theme={null}
pipeline {
    agent any

    stages {
        stage('Malware Scan') {
            steps {
                sh 'vet scan -D . --malware-query --report-json malware-results.json'
                archiveArtifacts artifacts: 'malware-results.json'
            }
        }
    }
}
```

## Troubleshooting

> [accordion] Legitimate packages are flagged
>
> * Review the analysis details
> * Contact SafeDep support with the package details
> * Use exceptions management for temporary overrides

> [accordion] A package is not flagged as malicious
>
> * Only packages already present in SafeDep's known malicious packages database are reported. Packages not yet analyzed are not flagged.
> * Ensure you are using the latest version of Vet
> * Check network connectivity to SafeDep Cloud

> [card] [On-Demand Package Scanning](https://docs.safedep.io/package-security/scan/overview)
>
> Run an on-demand analysis of a package, IDE extension, or GitHub repository not yet in the database

> [card] [vet-action Documentation](https://github.com/safedep/vet-action?tab=readme-ov-file#cloud-mode)
>
> Complete GitHub Actions integration guide

> [card] [SafeDep Cloud Setup](https://docs.safedep.io/governance/cloud/quickstart.md)
>
> Optional cloud features such as report sync and higher rate limits

> [card] [Report Issues](https://github.com/safedep/vet/issues)
>
> Report bugs or request features for malware analysis


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.