Skip to content

docs: simplify malware analysis for query-only, keyless workflow #76

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Sahilb315 merged 3 commits into from
Jul 23, 2026
+47 −110
Merged

docs: simplify malware analysis for query-only, keyless workflow #76

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0f0da0e
docs: simplify malware analysis for query-only, keyless workflow
KunalSin9h Jul 23, 2026
8fe43e1
docs: address review feedback on malware analysis page
KunalSin9h Jul 23, 2026
184cd18
docs: drop Steps component for single install requirement
KunalSin9h Jul 23, 2026
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
5 changes: 3 additions & 2 deletions faq.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -118,9 +118,10 @@ Common causes:
</Accordion>

<Accordion title="Malware analysis">
If using `--malware`, adjust the timeout:
Malware detection with `--malware-query` is a fast lookup against SafeDep's
known malicious packages database and adds negligible overhead:
```bash
vet scan -D . --malware --malware-analysis-timeout 5m
vet scan -D . --malware-query
```
</Accordion>

Expand Down
152 changes: 44 additions & 108 deletions governance/cloud/malware-analysis.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,15 @@
---
title: Malware Analysis
description: "Detect malicious packages in your dependencies using SafeDep Cloud's advanced code analysis capabilities"
description: "Detect malicious packages in your dependencies by querying SafeDep's known malicious packages database"
---

<Note>Malware analysis is available for free with SafeDep Cloud. See [pricing](https://safedep.io/pricing) for details.</Note>
<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.</Note>

Analyze open source packages for malicious code using [Vet](https://github.com/safedep/vet) with SafeDep Cloud's hosted analysis service. The service scans package artifacts from public package registries.
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>
Active (on-demand) analysis of arbitrary packages has been retired. Vet now performs a fast lookup against known malicious packages instead of submitting packages for analysis and waiting for results.
</Note>

## Supported Ecosystems

Expand All @@ -32,66 +36,52 @@ Analyze open source packages for malicious code using [Vet](https://github.com/s

## Requirements

<Steps>
<Step title="Install Vet">
You must have [Vet](https://github.com/safedep/vet) version `1.9.7` or above installed.
</Step>

<Step title="SafeDep Cloud Access">
You must be onboarded to SafeDep Cloud with a Tenant Domain and API Key. See [SafeDep Cloud Quickstart](/governance/cloud/quickstart) for onboarding instructions.
</Step>
</Steps>
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](/governance/cloud/quickstart).
</Note>

## Repository Scanning

### Basic Malware Scanning

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

```bash
vet scan -D /path/to/code --malware
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>
`vet` waits for a timeout period for malware analysis to complete. This works well for pull requests and CI/CD pipelines where the number of changed packages is small.
The `--malware` flag is a deprecated alias for `--malware-query` and behaves identically. It will be removed in a future release.
</Note>

### Timeout Configuration

Adjust analysis timeout for different scenarios:

```bash
# Quick scan with shorter timeout
vet scan -D . --malware --malware-analysis-timeout 5m

# Thorough scan with longer timeout
vet scan -D . --malware --malware-analysis-timeout 15m
```

### Specific Manifest Scanning

Scan individual package manifest files:

```bash
# npm projects
vet scan -M package-lock.json --malware
vet scan -M package-lock.json --malware-query

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

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

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

### PURL-Based Scanning

Scan specific packages using Package URLs:

```bash
vet scan --purl pkg:npm/llm-oracle@1.0.2 --malware
vet scan --purl pkg:npm/llm-oracle@1.0.2 --malware-query
```

<img src="/images/vet-malysis-llm-oracle.png" alt="Malware analysis results for llm-oracle package" />
Expand All @@ -101,7 +91,7 @@ vet scan --purl pkg:npm/llm-oracle@1.0.2 --malware
Scan locally installed VS Code extensions:

```bash
vet scan --vsx --malware
vet scan --vsx --malware-query
```

<Warning>
Expand All @@ -110,7 +100,7 @@ VS Code extension scanning is supported only for local developer machines, not i

## GitHub Actions Integration

### vet-action Cloud Mode
### vet-action

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

Expand All @@ -125,17 +115,17 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- name: Run malware analysis
uses: safedep/vet-action@v1
with:
cloud: true
cloud-key: ${{ secrets.SAFEDEP_CLOUD_API_KEY }}
cloud-tenant: ${{ secrets.SAFEDEP_CLOUD_TENANT_DOMAIN }}
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.
</Note>

### Pull Request Integration

When enabled, Vet scans changed packages for malware and provides results directly in pull requests:
Expand All @@ -146,44 +136,6 @@ Expand comments to view detailed package analysis results:

<img src="/images/vet-action-malysis-2.png" alt="Detailed malware analysis results in PR" />

## Package Inspection

### Enable Experimental Feature

Package inspection is currently experimental. Enable it with:

```bash
export VET_ENABLE_PACKAGE_INSPECT_COMMAND=true
```

### Inspect Single Packages

Perform detailed analysis of individual packages:

```bash
vet inspect malware --purl pkg:npm/llm-oracle@1.0.2
```

<Note>
Package analysis is performed asynchronously. Scanning usually takes a few minutes but may take longer depending on the analysis queue.
</Note>

### Analysis Results

On completion, Vet shows the analysis status and classification:

<img src="/images/llm-oracle-npm-malysis.png" alt="Malware scan result showing package classification" />

### Export Results

Export analysis results as JSON:

```bash
vet inspect malware \
--purl pkg:npm/llm-oracle@1.0.2 \
--report-json /tmp/analysis.json
```

## Understanding Results

### Classification Levels
Expand All @@ -192,21 +144,23 @@ vet inspect malware \
- **SUSPICIOUS**: Potentially risky patterns identified
- **MALICIOUS**: Confirmed malicious behavior found

### Analysis Techniques
### 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:

<AccordionGroup>
<Accordion title="Static Analysis">
- Code pattern analysis
- Suspicious function detection
- Obfuscation identification
</Accordion>

<Accordion title="Behavioral Analysis">
- Network communication patterns
- File system access patterns
- Process execution analysis
</Accordion>

<Accordion title="Metadata Analysis">
- Package metadata anomalies
- Publisher reputation analysis
Expand All @@ -226,32 +180,23 @@ malware-scan:
stage: security
image: ghcr.io/safedep/vet:latest
script:
- vet scan -D . --malware --report-json malware-report.json
- vet scan -D . --malware-query --report-json malware-report.json
artifacts:
reports:
security: malware-report.json
variables:
SAFEDEP_API_KEY: $SAFEDEP_API_KEY
SAFEDEP_TENANT_ID: $SAFEDEP_TENANT_ID
```

### Jenkins Pipeline

```groovy
pipeline {
agent any

environment {
SAFEDEP_API_KEY = credentials('safedep-api-key')
SAFEDEP_TENANT_ID = credentials('safedep-tenant-id')
}


stages {
stage('Malware Scan') {
steps {
sh 'vet scan -D . --malware --report-json malware-results.json'
sh 'vet scan -D . --malware-query --report-json malware-results.json'
archiveArtifacts artifacts: 'malware-results.json'
publishTestResults testResultsPattern: 'malware-results.json'
}
}
}
Expand All @@ -261,34 +206,25 @@ pipeline {
## Troubleshooting

<AccordionGroup>
<Accordion title="Analysis times out frequently">
- Increase the timeout with `--malware-analysis-timeout`
- Scan smaller package sets
- Check network connectivity to SafeDep Cloud
</Accordion>

<Accordion title="Authentication errors">
- Verify your API key has malware analysis permissions
- Check your tenant configuration
- Ensure you are using Vet v1.9.7 or later
</Accordion>

<Accordion title="Legitimate packages are flagged">
- Review the analysis details
- Contact SafeDep support with the package details
- Use exceptions management for temporary overrides
</Accordion>

<Accordion title="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
</Accordion>
</AccordionGroup>

<CardGroup cols={2}>
<Card title="vet-action Documentation" icon="github" href="https://github.com/safedep/vet-action?tab=readme-ov-file#cloud-mode">
Complete GitHub Actions integration guide
</Card>
<Card title="SafeDep Cloud Setup" icon="cloud" href="/governance/cloud/quickstart">
Get started with SafeDep Cloud for malware analysis
</Card>
<Card title="Package Inspection Guide" icon="magnifying-glass" href="https://github.com/safedep/vet#package-inspection">
Learn more about experimental package inspection features
Optional cloud features such as report sync and higher rate limits
</Card>
<Card title="Report Issues" icon="bug" href="https://github.com/safedep/vet/issues">
Report bugs or request features for malware analysis
Expand Down