Revise README for clarity and structure
Updated README.md to enhance formatting, improve descriptions, and add sections.
This commit is contained in:
Zeecka
@@ -6,101 +6,195 @@
|
|||||||
[](https://aperisolve.com/)
|
[](https://aperisolve.com/)
|
||||||
[](https://inventory.raw.pm/tools.html#Aperi'Solve)
|
[](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">
|
<a href="https://buymeacoffee.com/aperisolve">
|
||||||
<img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" height="40" />
|
<img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" height="40" />
|
||||||
</a>
|
</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:
|
Recommended: Docker + Docker Compose.
|
||||||
- **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:
|
|
||||||
|
|
||||||
|
Clone and start the full stack (production-like):
|
||||||
```bash
|
```bash
|
||||||
git clone https://github.com/Zeecka/AperiSolve.git
|
git clone https://github.com/Zeecka/AperiSolve.git
|
||||||
cd aperisolve
|
cd AperiSolve
|
||||||
docker compose up -d
|
docker compose up -d
|
||||||
```
|
```
|
||||||
|
|
||||||
> Default will run on http://localhost:5000/
|
Default: http://localhost:5000/
|
||||||
|
|
||||||
## Development
|
## Development
|
||||||
|
Development compose:
|
||||||
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.
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
docker compose down -v # Remove the volume containings results
|
# development environment (hot reload and local volumes)
|
||||||
docker compose -f compose.dev.yml up # Start application in developpement mode
|
docker compose -f compose.dev.yml up --build
|
||||||
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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
> 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
|
Note: If switching between dev and production compose files, remove the `results` directory or mounted volume to avoid conflicts:
|
||||||
- Flake8 (ignoring E203,E501,W503)
|
```bash
|
||||||
- Pylint (ignoring W0718,R0903,R0801)
|
rm -rf aperisolve/results
|
||||||
- Mypy (ignoring unused-awaitable)
|
```
|
||||||
|
### 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
|
## Roadmap
|
||||||
|
|
||||||
- [ ] Zsteg extract / --all --> **Download `zsteg` files** such as mp3 encoded on LSB
|
- [ ] zsteg: full extraction (--all) and download of discovered files (mp3, etc.)
|
||||||
- [ ] Test on mobile
|
- [ ] Mobile-friendly UI / test on mobile
|
||||||
- [ ] i18n
|
- [ ] i18n (internationalization)
|
||||||
- [ ] Rootless analyzers ?
|
- [ ] 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).
|
||||||
|
|||||||
Reference in New Issue
Block a user