Project guide for engineers (and Claude) working on QuadCore SQLi. Keep this file factual and in sync with the code — when architecture or endpoints change, update this file in the same change.
QuadCore SQLi is an async SQL-injection testing toolkit (target DBMS:
MySQL/MariaDB) for authorized security testing — see
DISCLAIMER.md. It is a 2026 rewrite of a 2017 PHP/AngularJS
tool, which is kept for reference in legacy/ and is not
maintained.
engine/ pure async SQLi library — no web framework, no persistence, no UI.
Only external dependency: httpx.
api/ FastAPI service: exposes the engine over HTTP/WebSocket, manages
jobs as asyncio tasks, persists job state in SQLite (aiosqlite).
web/ Vite + React + TypeScript SPA. Built separately (`npm run build`
→ web/dist); not part of the Python package.
engine/ never imports from api/. It can be used as a standalone library.
engine/models.py— core dataclasses/enums:InjectionContext(numeric,single_quote,double_quote,paren_single,paren_numeric),Technique(error,boolean,time,union),HttpResponse,Param,Target,InjectionPoint,Finding.engine/target.py—parse_target(url)extracts query params;injection_points(target, contexts)builds oneInjectionPointper (param, context);build_url/build_rawrender a payload into a URL, wrapping it per injection context (e.g. closing a quote + paren +-- -).engine/http/client.py—AsyncHttpClient: httpx-based client with a concurrency semaphore, user-agent rotation, retry with backoff on transport errors, and (viaengine/http/pacing.py'sRateLimiter) per-host request pacing with jitter.engine/detection/— one detector per technique, all implementingDetector.detect(client, point) -> DetectionResult | None:error.py—ErrorDetector: baseline must be clean, a bare'probe must trigger a SQL error (signatures.py's regex of MySQL/MariaDB error strings).boolean.py—BooleanDetector:AND 1=1vsAND 1=2responses must diverge (viadifflib.SequenceMatchersimilarity) whileAND 1=1stays close to the baseline.timing.py—TimeDetector:AND SLEEP(n)must add roughlynseconds versusAND SLEEP(0).union.py—UnionDetector: brute-forces column count withUNION SELECT NULL,...until the error disappears, then finds the reflected ("visible") column by injecting a unique marker string.engine.py—DetectionEngine/default_detectors(): orchestrator that runs all detectors against every injection point and collects every technique that works (not just the first), so exploitation can pick the best one.
engine/exploit/— the unified extractor: a singleValueReaderinterface (read(expr) -> str) with two implementations, so schema/row dumping code doesn't care which technique confirmed the injection:reader.py'sUnionReader— fast path: reflectsconcat(0x<sep>,(expr),0x<sep>)through the visible UNION column and slices the value out between separators.reader.py'sBlindReader— binary-search char-by-char: first binary-searcheslength((expr)), then binary-searches each byte's ASCII value viaoracle.py'sOracle.is_true(condition).oracle.py'sBooleanOracle— the blind oracle: compares a condition's response to a cachedAND 1=1baseline via similarity ratio.
engine/fingerprint/mysql.py—fingerprint(reader): readsversion()/current_user()/database()through anyValueReader.engine/dump/—schema.pywalksinformation_schema(databases → tables → columns) through aValueReader;rows.py'sdump_rowsfetches rows concurrently (bounded by a semaphore) with anon_rowcallback for progress/checkpointing and astartoffset for resuming an interrupted dump.engine/dorks/—library.py'sDorkLibraryis a curated, categorized set of dork templates (generic/ecommerce/news/cms);searxng.py'sSearxngClientqueries a self-hosted SearXNG instance's JSON API (not scraping search engines directly);pipeline.py'sfilter_candidatesremoves blocklisted hosts (search engines, social networks, code hosts, docs sites) and non-parameterized/duplicate URLs from the results.engine/tamper/— a pluggable WAF-evasion chain:base.py'sTamperprotocol +apply_chain;tampers.pyprovidesRandomCase,Space2Comment,HexLiterals,UrlEncode, plus thehexify/unhex_hex_casthelpers used throughout the exploit/dump code to avoid literal quotes in payloads.
api/config.py—Settings(pydantic-settings), env-driven, prefixQCSQLI_, also reads a.envfile. See Configuration below.api/main.py—create_app()builds the FastAPI app; itslifespanconnects aJobStoreand constructs theJobManagerwith the handler registry, stored onapp.state. Module-levelappis the ASGI entrypoint (api.main:app). CORS is currently open (allow_origins=["*"]).api/routes.py— the HTTP/WebSocket surface, see API below.api/jobs/manager.py—JobManagerruns each job as anasyncio.Task, persists status/progress/result throughJobStore, and fans out events to WebSocket subscribers via per-jobasyncio.Queues. Cancellation is cooperative (asyncio.CancelledErrorinside the running handler).api/jobs/handlers.py— one async handler per job type; see Job types.api/jobs/store.py—JobStore: SQLite (aiosqlite) persistence;Jobdataclass;JobStatusStrEnum(queued,running,done,error,cancelled);params/resultare stored as JSON text.
Not present on disk yet in this branch — built separately with
npm run build, producing web/dist, which is what the web nginx service
in docker-compose.yml serves. The SPA is a thin client over the API below;
it does not talk to the engine directly.
| type | params | does |
|---|---|---|
scan |
url, contexts? (list of InjectionContext values) |
Runs DetectionEngine over every injection point of url, returns all findings (technique, confidence, details) per param/context. |
dork |
dorks (list of str), pages? (default 1), searxng_url? (default settings.searxng_url) |
Queries SearXNG for each dork, returns filtered candidate URLs (filter_candidates, require_params=True). |
dump |
url, context? (default numeric), param, technique (union/other→blind), num_columns, visible_index (union only), db, table, columns (list), concurrency? (default 5) |
Builds a ValueReader (UnionReader or BlindReader+BooleanOracle) for the confirmed injection point, then dump_rows into {db, table, columns, rows, count}. |
All three report progress via ctx.progress(percent, message), which the
manager persists and broadcasts over WebSocket.
POST /api/jobs— body{"type": "scan"|"dork"|"dump", "params": {...}}, optionalX-Tokenheader (see auth below). Returns{"id": <int>}.400on an unknown job type.GET /api/jobs— list all jobs (most recent first), each as{id, type, status, progress, message, result, error, params, created_at, updated_at}.GET /api/jobs/{job_id}— single job, same shape;404if unknown.POST /api/jobs/{job_id}/cancel— cooperatively cancels a running job;409if the job isn't currently active.GET /api/dorks/library—{"categories": {<name>: [<dork>, ...], ...}}fromDorkLibrary.WS /api/jobs/{job_id}/stream— streams JSON events for that job:{"event": "status", "status": "running"},{"event": "progress", "progress": <float>, "message": <str>},{"event": "done", "result": {...}},{"event": "error", "error": <repr(exc)>},{"event": "cancelled"}. The connection closes after a terminal event.
POST /api/jobs checks the X-Token header against Settings.token
only if QCSQLI_TOKEN is set; otherwise the endpoint is open. No other
endpoint is currently gated. Treat this as "trusted network" software: put it
behind the localhost bind (below) and/or a reverse proxy that adds real auth
if it's ever reachable beyond your own machine.
| var | default | meaning |
|---|---|---|
QCSQLI_HOST |
127.0.0.1 |
intended bind address — do not change to 0.0.0.0 unless the process is already sandboxed (container, firewall) and only reachable from trusted callers. This default exists specifically so the tool can't become an open SSRF relay. Gotcha: nothing in api/ currently reads settings.host/settings.port — the actual bind is whatever --host/--port you pass to the uvicorn process (e.g. the Dockerfile's CMD, or your local uvicorn api.main:app invocation). Keep these two in sync by hand until/unless api/main.py reads settings.host/.port itself. |
QCSQLI_PORT |
8000 |
intended bind port — see gotcha above. |
QCSQLI_TOKEN |
None |
if set, required as X-Token on POST /api/jobs. |
QCSQLI_SEARXNG_URL |
http://searxng:8080 |
base URL of the SearXNG instance used by dork jobs. |
QCSQLI_CONCURRENCY |
10 |
AsyncHttpClient concurrency semaphore size. |
QCSQLI_PER_HOST_DELAY |
0.0 |
minimum seconds between requests to the same host (politeness/rate-limit avoidance). |
QCSQLI_DB_PATH |
quadcore.sqlite3 |
SQLite file for the job store. |
cd web && npm install && npm run build && cd .. # produces web/dist
docker compose up --build # api, searxng, web- API:
http://127.0.0.1:8000— SPA:http://127.0.0.1:8081(proxies/api) — SearXNG:http://127.0.0.1:8080. All bound to localhost only. - Vulnerable test target (local integration testing only):
docker compose --profile test up --build vuln-target→http://127.0.0.1:8090/index.php?id=1.depends_ononly orders container startup, not readiness — on the very first run, MySQL needs a few seconds to finish initializing beforeindex.phpcan connect; retry once.
python -m venv .venv && . .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
uvicorn api.main:app --reload # API on 127.0.0.1:8000
cd web
npm install
npm run dev # Vite dev serverpytest # asyncio_mode = auto, testpaths = tests (see pyproject.toml)
ruff check .
mypy enginetests/mirrorsengine//api/package layout 1:1.tests/helpers/fake_app.pyis a small in-process SQL evaluator (handlesconcat/hex/conditions) used to unit-test detectors/exploit code without a real HTTP server or database — check it before writing new engine tests.tests/helpers/fake_reader.pyprovides a fakeValueReaderfor fingerprint/dump tests that shouldn't depend on the real extraction path.- ruff: line-length 100, target
py311, rulesE, F, I, UP, B. - mypy:
python_version = 3.11,disallow_untyped_defs = false,warn_unused_ignores = false,ignore_missing_imports = true.
- Python ≥ 3.11 (project requires
>=3.11; CI/tooling targets 3.11).from __future__ import annotationsat the top of every module. - Enums are
enum.StrEnum(JobStatus,InjectionContext,Technique), not plainstr, Enummixins. - Data holders are
@dataclass(plain orfrozen=Truefor immutable value types likeHttpResponse/Param). - Interfaces are structural (
typing.Protocol), not ABCs:Detector,Oracle,ValueReader,Tamper. Prefer adding a new class that satisfies the protocol over widening an existing one. engine/stays dependency-pure: httpx only, no FastAPI/pydantic/aiosqlite imports. If something needs those, it belongs inapi/.- ruff-enforced line length: 100 columns.
- Job handlers (
api/jobs/handlers.py) are the seam betweenapi/andengine/: they translate adict[str, Any]params payload intoengine/calls and report progress viaJobContext. Keep engine code unaware of jobs/HTTP entirely.