Evidence-Based · Verification-Driven Bug Bounty Automation
Authorization comes first. CYGNUS will not touch a target until the operator explicitly confirms permission, supplies an authorization reference, and the target matches a required allowlist. Use it only on assets you own, an in-scope bounty target, or systems for which you have written permission.
CYGNUS is an asset-aware security verification CLI. It fingerprints what actually answers, dynamically selects only relevant check plugins, discards candidates without captured evidence, computes confidence/severity centrally, and produces a traceable report. It does not emit a universal finding template or claim that a harmless reflection/version string is a confirmed exploit.
- Passive/detection-only by default. No guessed logins, uploads, writes, or exploit payloads.
--activerequires a distinct--active-authorizedconfirmation. The current built-in set remains detection-only; the gate exists for separately reviewed future active plugins.- Every attempt—allowed or denied—is appended to
.cygnus/audit.jsonlby default. ONLINEis selected only from runtime DNS/protocol reachability. Local files/directories and unreachable targets becomeOFFLINE-STATIC.- Offline findings are tagged
STATIC/UNCONFIRMEDand excluded from confirmed severity totals. - Captures are truncated and secret-pattern matches are redacted. Reports can still contain sensitive banners/content; handle them accordingly.
operator / CLI
│
▼
┌──────────────────────────────┐
│ authorization + scope + audit│ hard gate; runs before network access
└──────────────┬───────────────┘
▼
┌──────────┐ AssetProfile ┌─────────────────────────────────────┐
│fingerprint├───────────────►│ plugin discovery + applicability gate│
│DNS/TCP/ │ └──────────────┬──────────────────────┘
│TLS/HTTP/ │ ▼
│file magic│ ┌─────────────────────────────────────┐
└──────────┘ │ web · network · cloud · containers │
│ enterprise · supply-chain · IoT │
└──────────────┬──────────────────────┘
▼
┌─────────────────────────────────────┐
│ evidence validator + central scoring│
│ explicit chain dependency rules │
└──────────────┬──────────────────────┘
▼
Markdown / JSON report
A plugin is a class in cygnus/modules/<category>/checks.py exposing name, applies_to, requires_active, and async run(profile, context). Discovery is automatic; adding a folder does not change the engine or report schema.
CYGNUS supports Python 3.11 or newer, with an explicit Python 3.14.1 compatibility target. First, confirm the interpreter version, then clone or download the repository and enter the project directory.
python3.14 --version
# Expected for the exact requested runtime: Python 3.14.1git clone https://github.com/ARENJKY369/BUGFINDER.git
cd BUGFINDERCreate and activate a virtual environment:
python3.14 -m venv .venv
source .venv/bin/activate
python --versionIf python3.14 is not installed, install Python 3.14.1 through your operating system or the official Python distribution first. Inside the activated environment, python --version should report Python 3.14.1.
py -3.14 -m venv .venv
.venv\Scripts\Activate.ps1
python --versionOn Windows, py -0p lists installed Python runtimes. Confirm that the selected 3.14 runtime is Python 3.14.1 when exact patch-level matching is required.
Install the project and test dependencies from requirements.txt:
python -m pip install --upgrade pip
python -m pip install -r requirements.txtThe requirements file installs CYGNUS in editable mode together with the test dependencies declared by the project.
Run the exact Python 3.14.1 compatibility environment with:
tox -e py3141This target first verifies that the interpreter is exactly 3.14.1, then compiles CYGNUS and runs the complete test suite. tox -e py311 retains compatibility coverage for existing Python 3.11 installations.
Verify the installation:
python -m cygnus --help
pytestpython -m pip install -r requirements.txt installs CYGNUS in editable mode and makes the cygnus terminal command available. When returning to the project, you do not need to reinstall the dependencies; simply reactivate .venv.
Create a scope file without editing it manually:
python -m cygnus -t https://example.com --init-scope scope.txtThen start an interactive authorized scan:
python -m cygnus -t https://example.com --scope scope.txtCYGNUS asks for authorization and its reference before any target access.
Run CYGNUS only against an asset you own, an in-scope bug-bounty target, or a target for which you have written permission. Every scan requires an authorization reference and a scope allowlist.
Create scope.txt in the project directory and place one authorized asset on each line. Blank lines and # comments are ignored. Exact domains, wildcard subdomains, IP addresses, CIDRs, and local repository paths are supported.
# scope.txt
example.com
*.staging.example.com
192.0.2.0/24
/home/operator/authorized-repo
The target host must match an entry in the scope file. For example, scanning https://api.example.com requires either api.example.com or a matching wildcard entry in scope.
An authorization reference is your record of permission, not a value supplied by CYGNUS or its developers. It helps identify why you are allowed to scan the target. Examples include:
- A bug-bounty program name or public program URL
- An internal security ticket such as
YOUR-PERMISSION-REFERENCE - A penetration-test statement-of-work identifier
- A written approval or change-request identifier
Do not place passwords, API keys, access tokens, or other secrets in this field.
You may omit the authorization flags from an interactive command. CYGNUS will then ask whether you have permission and prompt for the reference before making network requests. The reference itself cannot be bypassed because it is part of the mandatory audit trail.
The simplest command requires only the target and scope file:
python -m cygnus TARGET --scope scope.txtCYGNUS will display prompts similar to:
Authorization gate: do you have explicit permission for TARGET? Type 'yes': yes
Authorization/scope reference: YOUR-PERMISSION-REFERENCE
python -m cygnus is the recommended cross-platform command. The package also installs the shorter cygnus command, and all existing positional-target commands remain compatible.
CYGNUS fingerprints the target first, then runs only the modules applicable to the detected asset types. Manual -m module selection is not required.
python -m cygnus https://example.com --scope scope.txtAfter adding the API to the scope file, pass it as a normal target. REST, GraphQL, API-documentation, authentication, and web checks are automatically selected or skipped according to fingerprint evidence.
python -m cygnus https://api.example.com \
--scope scope.txt \
--output api-report.mdUse --recon for fingerprinting only. It performs authorized DNS, TCP/banner, TLS, HTTP, and bounded metadata discovery, but does not run vulnerability check modules.
python -m cygnus -t example.com \
--scope scope.txt \
--recon \
--timeout 5Markdown is the default report format:
python -m cygnus https://example.com \
--scope scope.txt \
--format markdown \
--output report.mdpython -m cygnus https://example.com \
--scope scope.txt \
--format json \
--output report.jsonThe current version supports Markdown and JSON. --format html and --depth aggressive are not implemented options, so this README does not advertise them as supported commands.
Add the authorized local repository path to scope.txt, then pass the same path as both the target and --repository-path:
python -m cygnus /home/operator/authorized-repo \
--scope scope.txt \
--repository-path /home/operator/authorized-repo \
--output repository-report.mdLocal source findings appear in the STATIC/UNCONFIRMED section and are excluded from confirmed severity totals. The interactive authorization prompt still appears for local scans.
CI cannot answer interactive prompts, so it must provide the confirmation and reference explicitly:
python -m cygnus https://example.com \
--scope scope.txt \
--authorized \
--authorization-ref 'YOUR-PERMISSION-REFERENCE' \
--format json \
--output report.jsonReplace YOUR-PERMISSION-REFERENCE with your real bug-bounty program, ticket, or written-approval reference. Use a separate reference for active authorization where applicable.
Checks are passive by default. Enabling active modules requires a separate active confirmation in addition to normal authorization. In an interactive terminal, use:
python -m cygnus https://example.com \
--scope scope.txt \
--activeCYGNUS asks for the normal authorization reference and a second ACTIVE-AUTHORIZED confirmation. For non-interactive automation, all active authorization flags must be explicit:
python -m cygnus https://example.com \
--scope scope.txt \
--authorized \
--authorization-ref 'YOUR-PERMISSION-REFERENCE' \
--active \
--active-authorized \
--active-authorization-ref 'YOUR-ACTIVE-PERMISSION-REFERENCE'The scan is blocked if the normal authorization/reference or separate active confirmation is missing.
python -m cygnus --helpList all recognized asset types or dynamically discovered check plugins without starting a scan:
python -m cygnus --list-assets
python -m cygnus --list-modulesDetection remains automatic—the operator does not manually force an asset type.
The following example flags are not part of the current CYGNUS CLI:
-m api
--depth aggressive
--format html
Their current equivalents are:
- API scan: Pass the API URL as a normal target; modules are selected automatically.
- Recon: Use the supported
--reconflag for a fingerprint-only run. - Aggressive mode: This is intentionally unavailable; gated active checks use
--activeplus a second confirmation. - HTML report: Generate Markdown or JSON and use a trusted external renderer.
- Asset list: Use
python -m cygnus --list-assets; detected types are also shown in every report.
- Web/API: browser headers, untrusted-origin CORS, harmless reflected marker, public admin/API-documentation indicators, bounded OpenAPI discovery, and GraphQL introspection evidence.
- SSH/FTP/RDP/email/network: protocol banner/config capture and exact product/version correlation against the local NVD-derived cache. FTP anonymous access is detected only when advertised; no login is submitted.
- Cloud/storage: unauthenticated object-list response detection. Authenticated policy checks use only future operator-provided credentials; CYGNUS never discovers credentials itself.
- Kubernetes/Docker: unauthenticated identity endpoint detection (
/version,/_ping) only; no control-plane operation. - CMS/CRM/ERP: published exact product/version match against the cache, routed to manual verification because backports can invalidate banner-only conclusions.
- Git/CI/CD/package registries: public interface classification plus redacted secret patterns in an explicitly operator-provided local repository.
- OAuth/SSO: OpenID discovery metadata policy checks, including insecure issuers and advertised unsigned-token support.
- IoT/network devices: default-credential indicators only. No credentials are attempted.
The local cache at cygnus/data/cve_cache.json identifies its NIST NVD API source, per-CVE NVD links, and last-updated date. It is intentionally small, so a cache miss means “not matched,” never “not vulnerable.”
Confirmed counts contain only live, evidence-backed results that pass confidence rules. Weak indicators, harmless reflection, public-interface exposure, and version/CVE correlations are shown under Needs Manual Verification. Exploit chains are emitted only when every tag in a predefined dependency rule belongs to a confirmed finding.
The integration suite starts local vulnerable and secure HTTP, FTP, and Kubernetes-dashboard mocks. It asserts classification, explicit plugin skips, finding disappearance after secure reconfiguration, report differences, and a regression signature preventing the historical static-output failure.
Each finding includes a stable evidence ID, detected asset type, computed severity/confidence, timezone-aware UTC observed_at, exact component, captured evidence, root cause, exploitation vector, remediation, status, and optional locally cited CVE metadata. A final fail-closed pass removes findings with empty evidence, invalid timestamps/status, or asset tags not present in the fingerprint profile before severity totals or exploit chains are generated.
Applicable check plugins are independent async functions and execute concurrently. Inapplicable plugins remain explicit skipped ledger entries; protocol failures are isolated as error entries rather than converted into findings.
See AUDIT_REPORT.md for the hardcoded-output audit and the live verification replacement map.