virusxcheck 0.2.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (18) hide show
  1. virusxcheck-0.2.1/LICENSE +21 -0
  2. virusxcheck-0.2.1/PKG-INFO +218 -0
  3. virusxcheck-0.2.1/README.md +183 -0
  4. virusxcheck-0.2.1/html_reporter.py +629 -0
  5. virusxcheck-0.2.1/pyproject.toml +54 -0
  6. virusxcheck-0.2.1/setup.cfg +4 -0
  7. virusxcheck-0.2.1/tests/test_api.py +222 -0
  8. virusxcheck-0.2.1/tests/test_check_hash.py +174 -0
  9. virusxcheck-0.2.1/tests/test_cli.py +145 -0
  10. virusxcheck-0.2.1/tests/test_output.py +230 -0
  11. virusxcheck-0.2.1/tests/test_validation.py +183 -0
  12. virusxcheck-0.2.1/virusxcheck.egg-info/PKG-INFO +218 -0
  13. virusxcheck-0.2.1/virusxcheck.egg-info/SOURCES.txt +16 -0
  14. virusxcheck-0.2.1/virusxcheck.egg-info/dependency_links.txt +1 -0
  15. virusxcheck-0.2.1/virusxcheck.egg-info/entry_points.txt +2 -0
  16. virusxcheck-0.2.1/virusxcheck.egg-info/requires.txt +10 -0
  17. virusxcheck-0.2.1/virusxcheck.egg-info/top_level.txt +2 -0
  18. virusxcheck-0.2.1/virusxcheck.py +705 -0
virusxcheck-0.2.1/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Lewis Wigmore
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
virusxcheck-0.2.1/PKG-INFO ADDED
@@ -0,0 +1,218 @@
1
+ Metadata-Version: 2.4
2
+ Name: virusxcheck
3
+ Version: 0.2.1
4
+ Summary: Cross-check file hashes against Virus Exchange and VirusTotal databases
5
+ Author: Lewis Wigmore
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/lewiswigmore/virus.xcheck
8
+ Project-URL: Repository, https://github.com/lewiswigmore/virus.xcheck
9
+ Project-URL: Issues, https://github.com/lewiswigmore/virus.xcheck/issues
10
+ Keywords: malware,virustotal,virus-exchange,hash,security
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: Information Technology
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.8
16
+ Classifier: Programming Language :: Python :: 3.9
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Topic :: Security
22
+ Requires-Python: >=3.8
23
+ Description-Content-Type: text/markdown
24
+ License-File: LICENSE
25
+ Requires-Dist: requests~=2.31
26
+ Requires-Dist: python-dotenv~=1.0
27
+ Requires-Dist: colorama~=0.4.6
28
+ Requires-Dist: plotly~=5.18
29
+ Requires-Dist: tqdm~=4.66
30
+ Requires-Dist: ratelimit~=2.2
31
+ Requires-Dist: tabulate~=0.9
32
+ Provides-Extra: dev
33
+ Requires-Dist: pytest~=8.0; extra == "dev"
34
+ Dynamic: license-file
35
+
36
+ ```
37
+ ██╗ ██╗██╗██████╗ ██╗ ██╗███████╗ ██╗ ██╗ ██████╗██╗ ██╗███████╗ ██████╗██╗ ██╗
38
+ ██║ ██║██║██╔══██╗██║ ██║██╔════╝ ╚██╗██╔╝██╔════╝██║ ██║██╔════╝██╔════╝██║ ██╔╝
39
+ ██║ ██║██║██████╔╝██║ ██║███████╗ ╚███╔╝ ██║ ███████║█████╗ ██║ █████╔╝
40
+ ╚██╗ ██╔╝██║██╔══██╗██║ ██║╚════██║ ██╔██╗ ██║ ██╔══██║██╔══╝ ██║ ██╔═██╗
41
+ ╚████╔╝ ██║██║ ██║╚██████╔╝███████║██╗██╔╝ ██╗╚██████╗██║ ██║███████╗╚██████╗██║ ██╗
42
+ ╚═══╝ ╚═╝╚═╝ ╚═╝ ╚═════╝ ╚══════╝╚═╝╚═╝ ╚═╝ ╚═════╝╚═╝ ╚═╝╚══════╝ ╚═════╝╚═╝ ╚═╝
43
+ ```
44
+ <p align="left">
45
+ <a href="https://github.com/lewiswigmore"><img src="https://img.shields.io/badge/GitHub-Follow%20on%20GitHub-inactive.svg?logo=github"></a>
46
+ </p>
47
+
48
+ ## Overview
49
+ Virus.xcheck is a Python tool designed to check the existence of file hashes in the Virus Exchange database. Due to the storage method used by Virus Exchange, only SHA-256 hashes are supported. However, for other hash types, the tool will return VirusTotal data. The tool can read SHA-256 hashes from a CSV file or accept a single hash from the command line, verifying each one against the Virus Exchange database.
50
+
51
+ ## Features
52
+ - Reads hashes from a CSV file or a single hash from the command line
53
+ - Checks each hash against the Virus Exchange API with S3 bucket fallback
54
+ - Parallel processing for efficient handling of larger files
55
+ - Colorized, beautifully formatted output in the terminal
56
+ - Outputs the results in JSON or CSV format
57
+ - Command-line interface with multiple options
58
+ - API key management with .env file support
59
+ - Rate limiting to prevent API throttling
60
+ - Interactive HTML reports with visualisations
61
+
62
+ ## Requirements
63
+ - Python 3.8+
64
+
65
+ ## Installation
66
+
67
+ ### Using pip
68
+ Install the required packages using the provided requirements.txt file:
69
+
70
+ ```bash
71
+ pip install -r requirements.txt
72
+ ```
73
+
74
+ ### API Key Setup
75
+ 1. Get an API key from [Virus.Exchange](https://virus.exchange/)
76
+ 2. Create a `.env` file in the root directory with your API key:
77
+ ```
78
+ VIRUSXCHECK_API_KEY=your_api_key_here
79
+ ```
80
+ Alternatively, you can use the `--save-config` option to set your keys interactively:
81
+ ```bash
82
+ python virusxcheck.py --save-config
83
+ ```
84
+
85
+ ## Usage
86
+ Execute the script from the command line with the following options:
87
+
88
+ ### Check a single hash
89
+ ```bash
90
+ python virusxcheck.py -s "hash_value"
91
+ ```
92
+
93
+ ### Process multiple hashes from a CSV file
94
+ ```bash
95
+ python virusxcheck.py -f /path/to/your/hashes.csv
96
+ ```
97
+
98
+ ### Save results to a file
99
+ ```bash
100
+ python virusxcheck.py -f /path/to/hashes.csv -o /path/to/results.csv
101
+ python virusxcheck.py -s "hash_value" -o /path/to/results.json
102
+ ```
103
+
104
+ ### Generate HTML report
105
+ ```bash
106
+ python virusxcheck.py -f /path/to/hashes.csv --html report.html
107
+ ```
108
+
109
+ ### Disable colored output
110
+ ```bash
111
+ python virusxcheck.py -s "hash_value" --no-color
112
+ ```
113
+
114
+ ## Test Examples
115
+
116
+ ### Sample Hashes for Testing
117
+ ```
118
+ d00853e592bccd823027e7e685d88c5a1f76a5a36ec5b7073d49ee633b050cc8
119
+ 3965811a37eded16030a1dd4ac57119ce774bed4fcd70a232011f8f86efbfd83
120
+ 51919bdfd8bc0ebeec651efdd5d97dae7ad9532cb10f6efaa67c3dbc88ea7500
121
+ ```
122
+
123
+ ### Testing with Sample CSV
124
+ Create a file `test_hashes.csv` with the above hashes and run:
125
+ ```bash
126
+ python virusxcheck.py -f test_hashes.csv --html results/report.html -o results/output.csv
127
+ ```
128
+
129
+ ### Sample Output
130
+ When running the tool with the test hashes, you'll see output similar to:
131
+ ```
132
+ VirusTotal API integration enabled
133
+ Processing: 100%|██████████████████████| 3/3 [00:00<00:00, 5.85it/s]
134
+ HTML report saved to results/report.html
135
+ Results saved to results/output.csv
136
+ ```
137
+
138
+ The terminal will display detailed information about each hash, including:
139
+ - Detection status (found/not found)
140
+ - File metadata (size, type, first seen)
141
+ - Known filenames
142
+ - Tags associated with the sample
143
+ - VirusTotal detection statistics
144
+ - Download and reference links
145
+
146
+ ## Command-Line Arguments
147
+ - `-s, --single`: Single hash string to check
148
+ - `-f, --file`: Path to CSV file containing hashes
149
+ - `-o, --output`: Path to output file (CSV or JSON format)
150
+ - `--html`: Generate HTML report with interactive charts
151
+ - `--save-config`: Interactively save API keys to .env file
152
+ - `--no-color`: Disable colored output
153
+
154
+ ## Output Formats
155
+
156
+ ### Terminal Output
157
+ The tool produces a colored output in the terminal:
158
+ - Red for malicious files found in the database
159
+ - Green for clean files not found
160
+ - Yellow for warnings and errors
161
+ - Metadata display with file information, names, tags, and links
162
+
163
+ ### HTML Reports
164
+ The HTML reports include:
165
+ - Interactive charts showing detection rates and statistics
166
+ - File metadata and statistics
167
+ - Malware tag classification
168
+ - Detailed scan results from VirusTotal
169
+
170
+ ### JSON Output
171
+ ```json
172
+ {
173
+ "dbd5e933fe023ee03953ed8a8997c58be05ba97c092b795647962cf111bcd540": {
174
+ "status": "Found in VX database",
175
+ "details": {
176
+ "md5": "d51c19925a2ae853d3b19a1259f86de5",
177
+ "size": 4042752,
178
+ "type": "unknown",
179
+ "names": [
180
+ "csrss.exe",
181
+ "app.exe"
182
+ ],
183
+ "sha1": "332a18521f2905e233bbab094a021cee44ac750e",
184
+ "tags": [
185
+ "spreader",
186
+ "peexe",
187
+ "executable",
188
+ "windows"
189
+ ],
190
+ "first_seen": "2025-03-30T17:36:55Z",
191
+ "download_link": "https://s3.us-east-1.wasabisys.com/vxugmwdb/dbd5e933fe023ee03953ed8a8997c58be05ba97c092b795647962cf111bcd540"
192
+ },
193
+ "virustotal_url": "https://www.virustotal.com/gui/file/dbd5e933fe023ee03953ed8a8997c58be05ba97c092b795647962cf111bcd540"
194
+ }
195
+ }
196
+ ```
197
+
198
+ ### CSV Output
199
+ The CSV output includes columns for:
200
+ - Hash
201
+ - VX Status
202
+ - File Type
203
+ - Size
204
+ - First Seen
205
+ - Names
206
+ - VX URL
207
+ - Download Link
208
+ - VirusTotal URL
209
+ - VT Detection Rate
210
+ - VT Malicious
211
+ - VT Suspicious
212
+ - VT Clean
213
+ - VT Type
214
+ - VT First Seen
215
+ - VT Tags
216
+
217
+ ## Disclaimer
218
+ This tool is for informational purposes only. Ensure you have the right to access and check the hashes against the database and always comply with the terms of service of the Virus Exchange and VirusTotal APIs.
virusxcheck-0.2.1/README.md ADDED
@@ -0,0 +1,183 @@
1
+ ```
2
+ ██╗ ██╗██╗██████╗ ██╗ ██╗███████╗ ██╗ ██╗ ██████╗██╗ ██╗███████╗ ██████╗██╗ ██╗
3
+ ██║ ██║██║██╔══██╗██║ ██║██╔════╝ ╚██╗██╔╝██╔════╝██║ ██║██╔════╝██╔════╝██║ ██╔╝
4
+ ██║ ██║██║██████╔╝██║ ██║███████╗ ╚███╔╝ ██║ ███████║█████╗ ██║ █████╔╝
5
+ ╚██╗ ██╔╝██║██╔══██╗██║ ██║╚════██║ ██╔██╗ ██║ ██╔══██║██╔══╝ ██║ ██╔═██╗
6
+ ╚████╔╝ ██║██║ ██║╚██████╔╝███████║██╗██╔╝ ██╗╚██████╗██║ ██║███████╗╚██████╗██║ ██╗
7
+ ╚═══╝ ╚═╝╚═╝ ╚═╝ ╚═════╝ ╚══════╝╚═╝╚═╝ ╚═╝ ╚═════╝╚═╝ ╚═╝╚══════╝ ╚═════╝╚═╝ ╚═╝
8
+ ```
9
+ <p align="left">
10
+ <a href="https://github.com/lewiswigmore"><img src="https://img.shields.io/badge/GitHub-Follow%20on%20GitHub-inactive.svg?logo=github"></a>
11
+ </p>
12
+
13
+ ## Overview
14
+ Virus.xcheck is a Python tool designed to check the existence of file hashes in the Virus Exchange database. Due to the storage method used by Virus Exchange, only SHA-256 hashes are supported. However, for other hash types, the tool will return VirusTotal data. The tool can read SHA-256 hashes from a CSV file or accept a single hash from the command line, verifying each one against the Virus Exchange database.
15
+
16
+ ## Features
17
+ - Reads hashes from a CSV file or a single hash from the command line
18
+ - Checks each hash against the Virus Exchange API with S3 bucket fallback
19
+ - Parallel processing for efficient handling of larger files
20
+ - Colorized, beautifully formatted output in the terminal
21
+ - Outputs the results in JSON or CSV format
22
+ - Command-line interface with multiple options
23
+ - API key management with .env file support
24
+ - Rate limiting to prevent API throttling
25
+ - Interactive HTML reports with visualisations
26
+
27
+ ## Requirements
28
+ - Python 3.8+
29
+
30
+ ## Installation
31
+
32
+ ### Using pip
33
+ Install the required packages using the provided requirements.txt file:
34
+
35
+ ```bash
36
+ pip install -r requirements.txt
37
+ ```
38
+
39
+ ### API Key Setup
40
+ 1. Get an API key from [Virus.Exchange](https://virus.exchange/)
41
+ 2. Create a `.env` file in the root directory with your API key:
42
+ ```
43
+ VIRUSXCHECK_API_KEY=your_api_key_here
44
+ ```
45
+ Alternatively, you can use the `--save-config` option to set your keys interactively:
46
+ ```bash
47
+ python virusxcheck.py --save-config
48
+ ```
49
+
50
+ ## Usage
51
+ Execute the script from the command line with the following options:
52
+
53
+ ### Check a single hash
54
+ ```bash
55
+ python virusxcheck.py -s "hash_value"
56
+ ```
57
+
58
+ ### Process multiple hashes from a CSV file
59
+ ```bash
60
+ python virusxcheck.py -f /path/to/your/hashes.csv
61
+ ```
62
+
63
+ ### Save results to a file
64
+ ```bash
65
+ python virusxcheck.py -f /path/to/hashes.csv -o /path/to/results.csv
66
+ python virusxcheck.py -s "hash_value" -o /path/to/results.json
67
+ ```
68
+
69
+ ### Generate HTML report
70
+ ```bash
71
+ python virusxcheck.py -f /path/to/hashes.csv --html report.html
72
+ ```
73
+
74
+ ### Disable colored output
75
+ ```bash
76
+ python virusxcheck.py -s "hash_value" --no-color
77
+ ```
78
+
79
+ ## Test Examples
80
+
81
+ ### Sample Hashes for Testing
82
+ ```
83
+ d00853e592bccd823027e7e685d88c5a1f76a5a36ec5b7073d49ee633b050cc8
84
+ 3965811a37eded16030a1dd4ac57119ce774bed4fcd70a232011f8f86efbfd83
85
+ 51919bdfd8bc0ebeec651efdd5d97dae7ad9532cb10f6efaa67c3dbc88ea7500
86
+ ```
87
+
88
+ ### Testing with Sample CSV
89
+ Create a file `test_hashes.csv` with the above hashes and run:
90
+ ```bash
91
+ python virusxcheck.py -f test_hashes.csv --html results/report.html -o results/output.csv
92
+ ```
93
+
94
+ ### Sample Output
95
+ When running the tool with the test hashes, you'll see output similar to:
96
+ ```
97
+ VirusTotal API integration enabled
98
+ Processing: 100%|██████████████████████| 3/3 [00:00<00:00, 5.85it/s]
99
+ HTML report saved to results/report.html
100
+ Results saved to results/output.csv
101
+ ```
102
+
103
+ The terminal will display detailed information about each hash, including:
104
+ - Detection status (found/not found)
105
+ - File metadata (size, type, first seen)
106
+ - Known filenames
107
+ - Tags associated with the sample
108
+ - VirusTotal detection statistics
109
+ - Download and reference links
110
+
111
+ ## Command-Line Arguments
112
+ - `-s, --single`: Single hash string to check
113
+ - `-f, --file`: Path to CSV file containing hashes
114
+ - `-o, --output`: Path to output file (CSV or JSON format)
115
+ - `--html`: Generate HTML report with interactive charts
116
+ - `--save-config`: Interactively save API keys to .env file
117
+ - `--no-color`: Disable colored output
118
+
119
+ ## Output Formats
120
+
121
+ ### Terminal Output
122
+ The tool produces a colored output in the terminal:
123
+ - Red for malicious files found in the database
124
+ - Green for clean files not found
125
+ - Yellow for warnings and errors
126
+ - Metadata display with file information, names, tags, and links
127
+
128
+ ### HTML Reports
129
+ The HTML reports include:
130
+ - Interactive charts showing detection rates and statistics
131
+ - File metadata and statistics
132
+ - Malware tag classification
133
+ - Detailed scan results from VirusTotal
134
+
135
+ ### JSON Output
136
+ ```json
137
+ {
138
+ "dbd5e933fe023ee03953ed8a8997c58be05ba97c092b795647962cf111bcd540": {
139
+ "status": "Found in VX database",
140
+ "details": {
141
+ "md5": "d51c19925a2ae853d3b19a1259f86de5",
142
+ "size": 4042752,
143
+ "type": "unknown",
144
+ "names": [
145
+ "csrss.exe",
146
+ "app.exe"
147
+ ],
148
+ "sha1": "332a18521f2905e233bbab094a021cee44ac750e",
149
+ "tags": [
150
+ "spreader",
151
+ "peexe",
152
+ "executable",
153
+ "windows"
154
+ ],
155
+ "first_seen": "2025-03-30T17:36:55Z",
156
+ "download_link": "https://s3.us-east-1.wasabisys.com/vxugmwdb/dbd5e933fe023ee03953ed8a8997c58be05ba97c092b795647962cf111bcd540"
157
+ },
158
+ "virustotal_url": "https://www.virustotal.com/gui/file/dbd5e933fe023ee03953ed8a8997c58be05ba97c092b795647962cf111bcd540"
159
+ }
160
+ }
161
+ ```
162
+
163
+ ### CSV Output
164
+ The CSV output includes columns for:
165
+ - Hash
166
+ - VX Status
167
+ - File Type
168
+ - Size
169
+ - First Seen
170
+ - Names
171
+ - VX URL
172
+ - Download Link
173
+ - VirusTotal URL
174
+ - VT Detection Rate
175
+ - VT Malicious
176
+ - VT Suspicious
177
+ - VT Clean
178
+ - VT Type
179
+ - VT First Seen
180
+ - VT Tags
181
+
182
+ ## Disclaimer
183
+ This tool is for informational purposes only. Ensure you have the right to access and check the hashes against the database and always comply with the terms of service of the Virus Exchange and VirusTotal APIs.