Amsiggel (ⴰⵎⵙⵉⴳⴳⴻⵍ)

Amsiggel comes from the Amazigh verb siggel, "to search". An amsiggel is one who searches: someone who looks everywhere, closely, and doesn't stop at the surface. That's what this scanner does with every network and application it's pointed at.

What it does

Amsiggel is a network and web app scanner and security audit tool. It scans hosts or code for vulnerabilities and suggests fixes.

Network scanner

• Detects service and version (-sV). Scans run in a separate worker process as a non-root user, and nmap gets only CAP_NET_RAW, through file capabilities (Docker) or AmbientCapabilities (systemd), so SYN and UDP scans work. The web app itself has no capabilities at all. Without that capability it falls back to a TCP connect scan, skips UDP, and says so on the results page.
• IPv4 and IPv6. IPv6 targets are detected automatically and scanned with -6. CIDRs work for both; IPv6 ranges are capped at 4096 hosts per range, because sweeping a /64 isn't feasible, so list known addresses instead.
• Risky exposed services. Databases, caches, remote access (RDP, VNC, Telnet), SMB file sharing and orchestration APIs (Docker, Kubernetes, etcd) reachable on the network are flagged on their own, with advice to restrict them — whether or not they also carry a known CVE.

CVE detection with distro backport awareness

• Candidate CVEs come from NVD 2.0, matched by CPE. No key is needed; a free key raises the rate limit.
• Each candidate is then checked against the distro's own security data:
  • RHEL / Alma / Rocky / CentOS: the Red Hat Security Data API, per CVE (Fixed / Affected / Not affected / Will not fix).
  • Debian / Ubuntu: OSV, queried in the Debian:<release> / Ubuntu:<release> ecosystem.
• Exploited-in-the-wild signal. Each CVE is checked against CISA KEV (the Known Exploited Vulnerabilities catalogue) and given its EPSS exploit-probability score (FIRST.org). A KEV-listed CVE is marked exploited in the wild, sorted to the top, and — unless the distro already backported a fix — raised to at least high. This tells an operator which handful of the many CVEs to patch first.
• Lookups are cached in SQLite. OFFLINE_MODE=true suits air-gapped installs (pre-seed the cache, including the KEV catalogue, for use offline).

Web application scanner

• Checks transport (HTTP→HTTPS, HSTS, obsolete TLS), security headers, clickjacking, cookie flags (the "cookie stealing" surface), CORS, version banners, verbose errors and stack traces, and exposed files (.git, .env, backups, phpinfo, actuator…) with soft-404 detection.
• Runs a bounded same-origin crawl, then benign probes on the parameters it finds:
  • a random alphanumeric marker to detect unescaped reflection (the precondition for XSS);
  • a single quote to detect SQL error signatures (the injection surface);
  • a check for POST forms with no anti-CSRF token.
• Weakness classes that can't be judged from outside the app (IDOR, SSRF, deserialization, business logic) are covered in docs/attack-surface-catalog.md. Code, dependencies and Android/iOS builds are covered by the pre-production check below.

Pre-production security audit

• Upload the source code, an Android/iOS build, a container image reference and/or the live URL. Amsiggel runs Semgrep, gitleaks, OSV-Scanner, Trivy, OWASP ZAP (passive baseline), Nuclei (detection templates), testssl.sh, MobSF and its own web checks, then gives one verdict: fail (with each blocking issue marked), incomplete (a check couldn't run), pass with warnings or pass.
• A pass opens a short manual review of what tools can't judge (access control per role, business rules, secrets handling, logging, backups…). Once each item is confirmed, the check shows who approved it for production and when.

Scan queues and data retention

Scan queue

• Uses smart queuing for scans. The queue lives in an SQLite database, so queued and running scans survive restarts.
• Fair turns: each user runs at most one scan at a time, submitting many scans never blocks others.

Data retention and scale

• Scans are stored in SQLite.
• Finished scans older than RETENTION_DAYS (default 1095, i.e. 3 years) are deleted automatically once a day, with all their hosts and findings. Set it to 0 to keep everything.

Quick start (Docker Compose)

cp .env.example .env
# edit .env: SECRET_KEY, LDAP_* settings, ZAP_API_KEY and MOBSF_API_KEY
# edit deploy/Caddyfile: your hostname (or `tls internal` for an internal CA)
docker compose --profile release up -d --build

Open https://<your-host>/, sign in, add the network you're authorized for on the dashboard, and start a scan.

The release profile adds the OWASP ZAP and MobSF services used by the pre-production check. Leave it out (docker compose up -d --build) if you don't need them; those two checks then show as "not run".

For a first run before LDAP is ready, set LDAP_ENABLED=false with LOCAL_ADMIN_USER / LOCAL_ADMIN_PASSWORD. Remove these once LDAP works.

Native install (systemd)

sudo ./systemd/install.sh
sudoedit /etc/amsiggel/amsiggel.env   # LDAP settings
sudo systemctl enable --now amsiggel amsiggel-worker

The web app listens on 127.0.0.1:8000. Put nginx or Caddy with TLS in front of it. Only the worker unit gets CAP_NET_RAW; both units apply systemd hardening.

For the pre-production check, install the tools on the host as described in docs/pre-production-check.md.

OS compatibility

For a systemd install the recommended OSs are:

• AlmaLinux/RockyLinux 10
• AlmaLinux/RockyLinux 9
• Debian 13

For a docker-compose install, you can use Podman compose or Docker compose on any recent OS.

Operational notes

• Tell your network/SOC team the scanner's IP so IDS alerts are expected, and agree scan windows with partners.
• Back up the amsiggel-data volume (or /var/lib/amsiggel).
• If a scan page keeps saying "Waiting for the scan worker to start", the worker isn't running: check docker compose ps worker or systemctl status amsiggel-worker.

Project layout

backend/app/
  main.py              FastAPI routes + UI
  config.py            env-driven settings
  db.py                SQLite persistence, scan queue, retention
  worker.py            scan worker: queue, heartbeats, recovery, cleanup
  auth/ldap_auth.py    LDAP search+bind, group check, injection-safe escaping
  auth/session.py      signed HttpOnly session cookie
  scanners/network.py  nmap port scan (no ping), IPv4/IPv6, XML parsing
  scanners/cve.py      NVD + Red Hat + OSV lookups, confidence/backport notes
  scanners/threatintel.py  CISA KEV + EPSS enrichment (exploited-in-the-wild)
  scanners/exposure.py exposed-service classification (databases, RDP, Docker…)
  scanners/distro.py   distro detection, RPM version comparison
  scanners/webapp.py   safe web attack-surface checks
  scanners/runner.py   authorization, queueing, scan execution
  release/check.py     pre-production check: runs the tools, stores findings
  release/tools.py     Semgrep, gitleaks, OSV-Scanner, Trivy, Nuclei, testssl.sh adapters
  release/zap.py       OWASP ZAP passive baseline via its API
  release/mobsf.py     MobSF static analysis via its API
  release/gate.py      verdict rules and the manual review list
  release/archive.py   safe unpacking of uploaded archives
  release/storage.py   upload storage and cleanup
  release/proc.py      running the external tools with timeouts and cancellation
  i18n.py              loads the UI translations from locale/
  locale/<lang>.json   UI text, one file per language (en, ar); add a file to add a language
branding/              Amsiggel logo, icon, favicon (SVG + PNG)
docs/attack-surface-catalog.md, docs/pre-production-check.md, docs/hardening.md
docker-compose.yml, deploy/Caddyfile, systemd/

Roadmap

• Authenticated crawling in the pre-production check (a test account per application), so pages behind a login are covered.
• Scheduled recurring scans and email or report export (PDF/CSV).