You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
**Automate vulnerability scanning and reporting using open-source components.**
10
+
**Free, open-source vulnerability scanning and reporting for GitHub repositories.**
8
11
9
12
## What is VISaR?
10
13
11
-
VISaR (Vulnerability Identification, Scanning and Reporting) is an open-source tool designed to automatically scan code repositories for vulnerabilities. VISaR generates detailed CSV reports summarizing potential issues: an ideal solution for engineers and developers to make informed decisions regarding ensure code safety.
14
+
VISaR (Vulnerability Identification, Scanning and Reporting) is a free, open-source Python tool that automatically scans GitHub repositories for known vulnerabilities and generates detailed, actionable reports. Output is available in CSV, JSON, or as a self-contained interactive HTML dashboard, . pojyymaking it easy to review, share, and act on findings.
12
15
13
-
With usability in mind, VISaR is written in Python and uses
14
-
best-in-class open-source components; the [OSSF scorecard](https://github.com/ossf/scorecard) for vulnerability identification and the [OSV Database](https://osv.dev/) for vulnerability information.
16
+
VISaR uses best-in-class open-source components: the [OSSF Scorecard](https://github.com/ossf/scorecard) for vulnerability identification and the [OSV Database](https://osv.dev/) for vulnerability enrichment (severity, description, and aliases).
15
17
16
18
**Who is VISaR for?**
17
19
18
-
-**Data Engineers:**Quickly evaluate code before integrating it into your data platform.
19
-
-**Software Engineers:** Assess your own code for vulnerabilities before it reaches production systems.
20
-
-**Independent Developers and Hobbyists:** Verify code generated by AI assistants or community contributions.
20
+
-**Data Engineers:**Evaluate open-source libraries and frameworks before integrating them into your data platform.
21
+
-**Software Engineers:** Assess your codebase for known vulnerabilities before a release or production deployment.
22
+
-**Independent Developers and Hobbyists:** Verify code generated by AI assistants or sourced from the community.
21
23
22
24
23
25
## 1. Using VISaR
24
26
25
27
**Pre-requisites**
26
28
27
-
To use VISaR, ensure you have the following:
29
+
To use VISaR, ensure you have the following installed and configured:
28
30
29
-
- Python 3.8+ (the code was developed in Python 3.12)
- The most recent OSSF scorecard Docker image ([follow instructions here](https://github.com/ossf/scorecard?tab=readme-ov-file#installation))
32
-
- A classic Github auth token _(settings > Developer Settings > Personal access tokens > Tokens (classic))_ and set the scope to public_repo. This needs to be included in the `.env` file.
31
+
-[uv](https://docs.astral.sh/uv/) — Python package and environment manager. uv will automatically download Python 3.12+ if needed.
32
+
-[Docker Desktop](https://www.docker.com/products/docker-desktop/) — required to run the OSSF Scorecard container.
33
+
- The OSSF Scorecard Docker image, pulled locally:
34
+
35
+
```
36
+
docker pull gcr.io/openssf/scorecard:stable
37
+
```
38
+
39
+
- A classic GitHub personal access token _(Settings > Developer Settings > Personal access tokens > Tokens (classic))_ with the `public_repo` scope. This is stored in a `.env` file at the project root (never committed to version control).
40
+
41
+
**System Requirements**
42
+
43
+
- Python 3.12+ (managed automatically by uv)
44
+
- Docker Desktop with at least 2 GB of available memory
45
+
- Network access to the GitHub API (`api.github.com`) and the OSV API (`api.osv.dev`)
46
+
- Approximately 1 GB of free disk space for the OSSF Scorecard Docker image
3. Run the _setup_ PowerShell script from the root directory to create a virtual environment, install dependencies, and activate it:
46
69
47
-
```
48
-
./scripts/setup.ps1
49
-
```
70
+
A `.env.example` template is included at the project root for reference.
71
+
72
+
3. From the root directory, install dependencies. This creates `.venv` and installs everything from `pyproject.toml` in one step:
50
73
51
-
4. From the root directory, run the test suite using:
74
+
```
75
+
uv sync
76
+
```
77
+
78
+
4. From the root directory, run the test suite to verify everything is working:
52
79
53
-
```
54
-
python -m unittest discover -s tests
55
80
```
81
+
uv run python -m unittest discover -s tests
82
+
```
83
+
84
+
All tests should pass. If any fail, check the error message and ensure Docker Desktop is running and the OSSF Scorecard image has been pulled.
56
85
57
-
You should see that all tests have passed. If not, the error message should guide you to the problem.
58
-
59
-
5. Now you are ready to run the pipeline. From the root directory, move into the src folder, and run the application:
60
-
86
+
5. Move into the `src/` folder and run the application:
87
+
88
+
**Single repository scan (default CSV output):**
61
89
```
62
90
cd src/
63
-
python main.py <full-github-repo>
91
+
uv run python main.py <full-github-repo-url>
92
+
```
93
+
94
+
**Single repository scan with JSON output:**
95
+
```
96
+
uv run python main.py <full-github-repo-url> --output-format json
97
+
```
98
+
99
+
**Batch scan — scan multiple repositories from a text file:**
100
+
```
101
+
uv run python main.py --batch ../repos.txt
102
+
uv run python main.py --batch ../repos.txt --output-format json
103
+
```
104
+
105
+
The batch file should contain one GitHub repository URL per line. Lines starting with `#` and blank lines are ignored. A `repos.txt.example` file is provided as a template — copy it to `repos.txt` and replace the contents with your own repos (`repos.txt` is gitignored).
106
+
107
+
**Generate an HTML dashboard from all scan outputs in a directory:**
108
+
```
109
+
uv run python dashboard.py
64
110
```
65
111
112
+
Or point to a specific data directory:
113
+
```
114
+
uv run python dashboard.py <path-to-data-dir>
115
+
```
116
+
117
+
The dashboard is an ad-hoc step — run scans as many times as needed first, then generate the HTML report when you are ready to review. A single self-contained `dashboard.html` is written to the `data/` directory, embedding all scan datasets. Use the dropdown to switch between scans, the date filter to narrow by scan date, and the severity pills to focus on the most critical findings. Rows can be expanded to read the full vulnerability detail.
118
+
119
+
**CLI Reference**
120
+
121
+
| Argument | Type | Default | Description |
122
+
|---|---|---|---|
123
+
| `repo_url` | positional | — | Full GitHub repository URL. Required unless `--batch` is used. |
124
+
| `--batch FILE` | optional | — | Path to a text file containing one URL per line. Use instead of `repo_url`. |
| `-h` / `--help` | flag | — | Display help message and exit. |
127
+
128
+
**Exit codes:** `0` — completed successfully (including when no vulnerabilities are found). `1` — scan failed; see the `logs/` directory for details.
129
+
66
130
<br>
67
-
The CSV file generated by a successful run is ready to consume in a tool like Microsoft Excel, see Figure 1. The key columns for decisionmaking are the Severity and Details which together describe a given vulnerability.
131
+
The output file generated by a successful run is placed in the `data/` directory. The default CSV format is ready to open in Microsoft Excel or any spreadsheet tool — see Figure 1. The key columns for decision-making are **Severity** and **Details**, which together describe each finding.
68
132
69
133
<br>
70
134
<br>
@@ -77,21 +141,21 @@ The CSV file generated by a successful run is ready to consume in a tool like Mi
77
141
<p><strong>Figure 1:</strong> Example VISaR Output</p>
78
142
</div>
79
143
80
-
Example logs for a successful run and a failed run are provided in the [logs directory](./logs/).
144
+
Example logs for a successful run and a failed run are provided in the [logs directory](./logs/). Example scan output files (CSV and JSON) are provided in the [data directory](./data/); these show the format a real scan produces and can be used to generate a dashboard without running a full scan.
81
145
82
146
## 2. Technical Overview
83
-
The user provides a GitHub code repository URL to VISaR which then automatically performs a code scan, sends requests to the OSV API and enriches the data before writing vulnerability information to a CSV file.
147
+
The user provides a GitHub repository URL to VISaR, which automatically performs a vulnerability scan, queries the OSV API to enrich findings, and writes a structured report in the chosen format.
84
148
85
149
**How VISaR works:**
86
150
87
-
The workflow below aligns with the architecture diagram shown Figure 2.
151
+
The workflow below aligns with the architecture diagram shown in Figure 2.
88
152
89
153
1. OSSF Scorecard scans the repository and generates a summary file.
90
-
2. A second OSSF Scorecard scan generates a file of known vulnerabilties (saved temporarily).
91
-
3. A list of vulnerability IDs are harvested from the temporary data file.
92
-
4. Vulnerability IDs are sent to the OSV API with severity and summary description requested.
93
-
5. Key vulnerability information is extracted from the JSON payload.
94
-
6. The vulnerability IDs, severity, and plain-text summary are compiled into a structured CSV file.
154
+
2. A second OSSF Scorecard scan generates a file of known vulnerabilities (saved temporarily).
155
+
3. A list of vulnerability IDs is extracted from the temporary file.
156
+
4. Vulnerability IDs are sent to the OSV API to retrieve severity ratings and plain-text descriptions.
157
+
5. Key vulnerability information is extracted from the API response.
158
+
6. The vulnerability IDs, severity, and descriptions are compiled into a structured report (CSV or JSON, depending on the `--output-format` flag).
95
159
96
160
<br>
97
161
@@ -103,31 +167,35 @@ The workflow below aligns with the architecture diagram shown Figure 2.
103
167
<p><strong>Figure 2:</strong> VISaR Architecture Diagram</p>
104
168
</div>
105
169
106
-
107
-
**Overview of the Project Structure**
108
170
109
-
The VISaR codebase follows a typical src structure.
171
+
**Overview of the Project Structure**
172
+
173
+
The VISaR codebase follows a standard `src/` layout.
174
+
175
+
- The application code is in `src/`. `main.py` is the scan entry point and `dashboard.py` is the HTML report entry point.
176
+
177
+
- The `helpers/` package is a collection of modules, each containing a logical grouping of functions used in the main pipeline. `dashboard_funcs.py` handles all HTML generation and is intentionally separate from the scan pipeline.
110
178
111
-
- The application code is stored in the `src/` directory, with `main.py` being the entry point.
179
+
- Each module in `helpers/` has an associated test file in `tests/`. Within each test script, all tests for a given function are grouped into their own class. We aim for close to 100% test coverage.
112
180
113
-
- The `helpers/` package is a collection of modules, each containing a logical grouping of functions used in the main application.
181
+
- Run details are captured in a `.log` file in the `logs/` directory. If a run fails, this is the first place to look.
114
182
115
-
- Each module within the `helpers` package has an associated test file in the `tests/` directory. Within each test script, all of the tests for a given function are grouped into their own class. We aim to have close to 100% test coverage!
183
+
- The `data/` directory contains scan output files, named by date and repository (e.g. `20260320-owner-repo_vulnids.csv`). The suffix depends on the chosen format: `_vulnids.csv` (default) or `_vulnids.json`. Running `dashboard.py` writes a single `dashboard.html` to this directory, embedding all scan datasets.
116
184
117
-
- Run details are captured in a `.log` file found within the `logs/` directory. If a run fails, this is where you should start troubleshooting.
185
+
- Project dependencies are declared in `pyproject.toml` at the root. Running `uv sync` creates `.venv` and installs everything. The `scripts/` directory contains `setup.ps1` (Windows) and `setup.sh` (Mac/Linux) as convenience wrappers around `uv sync`.
118
186
119
-
- The `data/` directory is where you can find the output of completed runs. The files ending with `_vulnids.csv` are the main output containing the vulnerability information.
120
187
121
-
- A PowerShell script, `setup.ps1`, is provided in the `scripts/` directory. This script should be ran the first time using VISaR, it creates the virtual environment and installs all dependencies for you.
188
+
## 3. Roadmap
122
189
190
+
See [docs/ROADMAP.md](./docs/ROADMAP.md) for planned features and future direction.
123
191
124
-
## 3. Contribute
125
-
Thank you for wanting to contribute and improve VISaR! We welcome contributions from the community and are grateful for your support.
192
+
## 4. Contribute
193
+
Thank you for wanting to contribute to VISaR! We welcome contributions from the community.
126
194
127
-
Before contributing, please read our guidelines which describe our code styleand testing approach: [/docs/Contributing.md](./docs/Contributing.md).
195
+
Before contributing, please read our guidelines covering code style, linting, and testing: [docs/Contributing.md](./docs/Contributing.md).
128
196
129
197
By contributing to this project, you agree that your contributions will be licensed under the [Apache-2.0 License](LICENSE.txt).
130
198
131
-
## 4. License
199
+
## 5. License
132
200
133
201
VISaR is completely free, open-source, and licensed under the [Apache-2.0 License](LICENSE.txt).
0 commit comments