venus/aperisolve
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Revise README for clarity and structure

Browse Source 
Updated README.md to enhance formatting, improve descriptions, and add sections.
This commit is contained in:
Zeecka
2025-12-10 23:46:11 +01:00
committed by GitHub
parent d86416c97d
commit 5c2da5e187
1 changed files with 159 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+159 -65
View File
@@ -6,101 +6,195 @@
[![Website](https://img.shields.io/website?url=https%3A%2F%2Faperisolve.com)](https://aperisolve.com/)
[![Rawsec's CyberSecurity Inventory](https://inventory.raw.pm/img/badges/Rawsec-inventoried-FF5050_flat.svg)](https://inventory.raw.pm/tools.html#Aperi'Solve)
<p align="center"><a href="https://www.aperisolve.com"><img src="https://raw.githubusercontent.com/Zeecka/AperiSolve/main/examples/screenshot.png"/></a></p>
<p align="center">
<a href="https://www.aperisolve.com">
<img src="https://raw.githubusercontent.com/Zeecka/AperiSolve/main/examples/screenshot.png" alt="Aperi'Solve screenshot" />
</a>
</p>
<b>Try it now: https://www.aperisolve.com</b>
Try it now: **https://www.aperisolve.com**
<b> Support Aperi'Solve:</b>
Support Aperi'Solve:
<a href="https://buymeacoffee.com/aperisolve">
<img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" height="40" />
</a>
## What is Aperi'Solve?
Aperi'Solve is a platform which performs steganalysis on images.<br/>
---
The platform uses *layer analysis*, "*zsteg*", "*steghide*", "*outguess*", "*exiftool*", "*binwalk*", "*foremost*" and "*strings*" for deeper steganography analysis.
Aperi'Solve is an open-source steganalysis web platform that performs automated analysis on images to detect and extract hidden data using common steganography tools and techniques.
<p align="center"><a href="https://www.aperisolve.com"><img src="https://i.imgur.com/qiR1mlT.gif"/></a></p>
Table of contents
- [Key features](#key-features)
- [Quick start (Docker)](#quick-start-docker)
- [Development](#development)
- [Adding a new analyzer](#adding-a-new-analyzer)
- [Configuration & environment variables](#configuration--environment-variables)
- [Architecture](#architecture)
- [Troubleshooting & tips](#troubleshooting--tips)
- [Roadmap](#roadmap)
- [Contributing](#contributing)
### Why Aperi'Solve?
## Key features
Aperi'Solve has been created in order to have an "easy to use" platform which performs common steganalysis tests such as LSB or `steghide`. The platform is also a quick alternative for people who were note able to install tools like `zsteg` (ruby gem) properly.
- Visualize each bit layer (LSB and other layers) per image channel (R/G/B/Alpha).
- Browse and download each bit-layer image.
- Integrates and displays outputs from:
- zsteg (LSB text/data extraction)
- steghide (extraction with password)
- outguess (extraction with password)
- exiftool (metadata and geolocation)
- binwalk (embedded archives)
- foremost (carved files)
- pngcheck
- strings
- Worker queue architecture for offloading heavy/slow analyzers (Redis + background workers).
- Results stored for later browsing and download.
### Features
## Quick start (Docker)
Aperi'Solve is based on Python3 with Flask and PIL module, the platform supports the most common image formats like`.png`, `.jpg`, `.gif`, `.bmp`, `.jpeg`, `.jfif`, `.jpe`, `.tiff`...
In case you want to host your own version of https://www.aperisolve.com/.
The platform allows you to:
- **Visualize each bit layer** of each channel for a given image (ie. LSB of Red channel).
- **Browse** and **Download each bit layer image**.
- **Visualise `zsteg` information** such as text encoded on LSB
- **Download `steghide` files** using a defined password
- **Download `outguess` files** using a defined password
- **Visualise `exiftool` information** such as geolocation or author
- **Visualise `binwalk` information**
- **Download `binwalk` files** such as ZIP file in PNG headers
- **Download `foremost` files** such as ZIP file in PNG headers
- **Visualise `pngcheck` output**
- **Visualise `strings` output**
## Installation
Even if Aperi'Solve is available at the URL https://www.aperisolve.com/, you can set up your own instance with the following command:
Recommended: Docker + Docker Compose.
Clone and start the full stack (production-like):
```bash
git clone https://github.com/Zeecka/AperiSolve.git
cd aperisolve
cd AperiSolve
docker compose up -d
```
> Default will run on http://localhost:5000/
Default: http://localhost:5000/
## Development
Aperi'Solve platform is a *Flask* web service (python 3.11+) with python workers performing analysis.
Jobs are stacked in a redis-queue, and image information is stored in a postgresql database.
All services run inside Docker containers.
### Adding new analyzer
Adding new analyzer is easy.
1. Copy and adapt the [template_analyzer.py](aperisolve/analyzers/template_analyzer.py) file with your name, ie. "myanalyzer.py".
2. Add this analyzer to [workers.py](aperisolve/workers.py).
- Import your function `from .analyzers.analyzer import analyze_myanalyzer`
- Add the function to the `analyzers` variable, like other analyzers.
3. Add your analyzer name to `TOOL_ORDER` in [aperisolve.js](aperisolve/static/js/aperisolve.js).
### Tips
Here is a batch of useful commands.
Development compose:
```bash
docker compose down -v # Remove the volume containings results
docker compose -f compose.dev.yml up # Start application in developpement mode
rm -rf aperisolve/results # Remove results from development mode
docker exec -it postgres psql -U aperiuser -d aperisolve # Get postgresql shell
docker exec -it aperisolve-web bash # Get a shell inside the running web app
# development environment (hot reload and local volumes)
docker compose -f compose.dev.yml up --build
```
> Note, if you used [compose.dev.yml](compose.dev.yml), you must remove "results" when switching to [production Docker](compose.yml) setup.
Useful commands:
```bash
# Stop and remove containers, networks and volumes (results are stored in a volume)
docker compose down -v
### Code quality
# Enter web container shell
docker exec -it aperisolve-web bash
Python code follows the following linters:
# Enter Postgres shell (from host)
docker exec -it postgres psql -U aperiuser -d aperisolve
```
- Black
- Flake8 (ignoring E203,E501,W503)
- Pylint (ignoring W0718,R0903,R0801)
- Mypy (ignoring unused-awaitable)
Note: If switching between dev and production compose files, remove the `results` directory or mounted volume to avoid conflicts:
```bash
rm -rf aperisolve/results
```
### Adding a new analyzer
GitHub CI will alert in case of failure.
Adding a custom analyzer is straightforward:
1. Create your analyzer file:
- Copy `aperisolve/analyzers/template_analyzer.py` -> `aperisolve/analyzers/myanalyzer.py`
- Implement function signature similar to:
```python
# aperisolve/analyzers/myanalyzer.py
def analyze_myanalyzer(image_path: str, results_dir: str) -> dict:
"""
Perform analysis on image located at image_path.
Produce outputs in results_dir and return a result dict (json-serializable).
"""
# your analysis logic here
return {"name": "myanalyzer", "status": "ok", "outputs": [...]}
```
2. Register the analyzer in the worker pipeline:
- Edit `aperisolve/workers.py`:
```python
# import
from .analyzers.myanalyzer import analyze_myanalyzer
# add to analyzers list (preserve the order)
analyzers = [
analyze_zsteg,
analyze_steghide,
# ...
analyze_myanalyzer,
]
```
3. Add your analyzer to the UI order:
- Edit `aperisolve/static/js/aperisolve.js` and append `myanalyzer` to `TOOL_ORDER` so it appears in the frontend.
4. Test locally: run the worker and submit jobs to ensure outputs are produced and displayed.
Tips:
- Keep analyzers idempotent and write outputs to the provided `results_dir`.
- Return structured JSON so the frontend can render links/downloads automatically.
## Configuration & environment variables
Typical services:
- Web app (Flask)
- Workers (Python)
- Redis (RQ)
- PostgreSQL
Main environment variables (examples):
- DATABASE_URL=postgresql://aperiuser:password@postgres:5432/aperisolve
- REDIS_URL=redis://redis:6379/0
- SECRET_KEY=change_me
- FLASK_ENV=production/development
If using Docker Compose, defaults are set in the compose files. For production deployments, set secure secrets via your orchestrator or environment.
## Architecture
- Flask web framework
- Background workers that run analyzers (queue via Redis)
- PostgreSQL stores image metadata and job statuses
- Docker-based deployment for isolation of analyzers and services
This separation keeps heavy tools (binwalk, foremost, zsteg, etc.) isolated and avoids blocking the web worker.
## Troubleshooting & tips
- If analyzers don't produce output, check worker logs:
```bash
docker compose logs -f aperisolve-worker
```
- To force re-analysis, remove results for the image (both file and in database) and re-submit the job.
- Ensure system packages needed by native tools (binwalk, foremost) are available in the analyzer containers or host image.
## Roadmap
- [ ] Zsteg extract / --all --> **Download `zsteg` files** such as mp3 encoded on LSB
- [ ] Test on mobile
- [ ] i18n
- [ ] Rootless analyzers ?
- [ ] zsteg: full extraction (--all) and download of discovered files (mp3, etc.)
- [ ] Mobile-friendly UI / test on mobile
- [ ] i18n (internationalization)
- [ ] Rootless / unprivileged analyzers
- [ ] Improve analyzer sandboxing (e.g., per-analyzer containers)
## Contributing
Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Open a pull request describing your change
Please follow the code style and run linters before submitting.
The project adheres to:
- Black
- Flake8 (ignoring E203, E501, W503)
- Pylint (ignoring W0718, R0903, R0801)
- Mypy (ignoring unused-awaitable)
CI will run these checks on each PR.
## Security
- If you discover a security issue, please report it privately to the repository owner instead of opening a public issue.
## Credits
Acknowledgements:
- Thanks to contributors and the open-source community for the tools integrated (zsteg, steghide, binwalk, foremost, exiftool).