ShadowScan

Static file analysis for malware triage, suspicious artifact detection, and scan history tracking.

ShadowScan is a Flask-based static analysis platform for inspecting suspicious files without executing them. It combines YARA rules, PE import analysis, document checks, and script inspection to produce a verdict, risk level, and historical scan record.

• Malware detection with 30+ YARA rules covering ransomware, trojans, backdoors, cryptominers, spyware, worms, rootkits, fileless patterns, and anti-analysis behavior.
• PE analysis with 85+ suspicious API import checks, including process injection, memory manipulation, anti-debugging, registry changes, and packer indicators.
• Script inspection for PowerShell, VBScript, JavaScript, Batch, and CMD files.
• Document-focused checks for PDFs and Office files, including macro, embedded object, JavaScript, and launch-action signals.
• Scan history persistence in PostgreSQL.
• Responsive web UI for file upload, analysis results, and history review.

• Executables: exe, dll
• Documents: doc, docx, pdf, xls, xlsx, ppt, pptx
• Scripts: ps1, vbs, js, bat, cmd
• Archives: zip, rar
• Text: txt

• Backend: Flask, SQLAlchemy
• Database: PostgreSQL
• Detection: YARA, pefile, python-magic
• Frontend: Bootstrap 5, Bootstrap Icons, vanilla JavaScript
• Deployment: Docker Compose

Use Docker if you want the fastest path to a working environment.

git clone https://github.com/GxAditya/ShadowScan.git
cd ShadowScan
docker compose up -d --build

Open the application at http://localhost:5000.

Useful commands:

docker compose ps
docker compose logs -f web
docker compose down

• Python 3.10 or newer
• PostgreSQL
• libmagic runtime installed on your system
• For Windows: Visual C++ Build Tools for yara-python

git clone https://github.com/GxAditya/ShadowScan.git
cd ShadowScan

Linux and macOS:

python3 -m venv .venv
source .venv/bin/activate

Windows PowerShell:

py -m venv .venv
.venv\Scripts\Activate.ps1

pip install -r requirements.txt

Create a .env file in the project root:

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/malware_analysis
SESSION_SECRET=replace-this-with-a-secure-random-value
UPLOAD_FOLDER=/tmp/uploads
MAX_CONTENT_LENGTH=10485760
DEBUG=False

Environment variable reference:

Make sure PostgreSQL is running and the target database exists, then initialize the tables:

python scripts/setup_db.py

python main.py

The app will be available at http://localhost:5000.

If yara-python fails to install on Windows:

1. Install Visual C++ Build Tools from Microsoft.
2. During setup, select the C++ workload.
3. Re-run pip install -r requirements.txt.

If you still need a manual YARA build:

git clone https://github.com/VirusTotal/yara.git
cd yara
python setup.py build
python setup.py install

Use the helper script to add new rules:

python scripts/add_yara_rule.py --name "CustomRule" --description "Detects custom patterns" --severity "medium"

You can paste the rule content interactively or pass a file with --file.

• Maximum upload size is 10 MB by default.
• Files are analyzed statically and are not executed.
• Uploaded files should be treated as sensitive and short-lived.
• Files are deleted after analysis.
• Path traversal is mitigated with secure filename handling.

• Docker deployment starts both the Flask app and PostgreSQL.
• The web service listens on localhost:5000.
• The database service listens on localhost:5432.
• Scan history is persisted in the Docker volume postgres_data.