🤝 Contribution

Thank you for considering a contribution to OpenDoor.

OpenDoor is an open-source CLI scanner for authorized web reconnaissance, directory discovery, and exposure assessment. Contributions should improve reliability, clarity, testability, documentation, packaging, or safe security-testing workflows.

---

🧭 Contribution principles

Good contributions are:

• focused;
• tested;
• easy to review;
• compatible with the current CLI behavior;
• documented when they change user-facing behavior;
• safe for public open-source distribution.

Prefer small, isolated pull requests over large mixed changes.

---

⚖️ Responsible security work

OpenDoor is a security testing tool. Contributions must support authorized testing only.

Do not contribute:

• exploit payload collections intended for abuse;
• credential theft logic;
• stealth or persistence features;
• destructive scanning behavior;
• malware-like behavior;
• real private VPN profiles, API tokens, cookies, bearer tokens, or credentials.

Do not commit real OpenVPN or WireGuard secrets.

Use examples only:

data/openvpn-profiles/example.ovpn
data/wireguard-profiles/example.conf

These files must contain placeholders, not real production credentials.

---

🛠️ Development setup

Clone the repository:

git clone https://github.com/stanislav-web/OpenDoor.git
cd OpenDoor

Create a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

Install development dependencies:

python -m pip install --upgrade pip setuptools wheel
python -m pip install -r requirements-dev.txt
python -m pip install -e .

Verify the CLI:

opendoor --version
opendoor --help

---

🌿 Branch workflow

Create a feature branch:

git checkout -b feature/my-change

Recommended branch prefixes:

Prefix	Purpose
feature/	New user-facing functionality
fix/	Bug fixes
docs/	Documentation-only changes
test/	Test-only changes
refactor/	Internal code cleanup without behavior change
release/	Release preparation

Keep commits focused. If a change touches code, tests, and docs, that is fine when all changes support the same feature or fix.

---

✅ Required checks

Before opening a pull request, run the relevant checks.

Full unit test suite

python -m unittest

Explicit discovery:

python -m unittest discover -s tests -p "test_*.py"

Coverage

coverage run -m unittest discover -s tests -p "test_*.py"
coverage report -m

Lint

ruff check .

Documentation

python -m mkdocs build --strict

If mkdocs is not available, use a documentation virtual environment:

python3 -m venv .docs-venv
source .docs-venv/bin/activate
python -m pip install -r docs/requirements.txt
python -m mkdocs build --strict

---

🧪 Test expectations

Every behavior change should include tests unless there is a clear reason not to.

Tests should be:

• deterministic;
• isolated;
• readable;
• free from real network dependencies;
• free from real VPN/process side effects;
• explicit about expected behavior.

Avoid increasing per-test timeouts to hide instability. Fix the underlying nondeterminism instead.

When a test fails, verify whether the failure comes from the test or from the implementation before changing assertions.

---

🧩 Areas that usually need tests

Change area	Expected test coverage
CLI option parsing	Unit tests for options and config propagation
Response filters	Unit tests for include/exclude behavior
Sniffers	Unit tests for plugin classification
Auto-calibration	Unit tests for baseline and matching behavior
Fingerprinting	Unit tests for known positive/negative samples
WAF detection	Unit tests for passive detection signals
Sessions	Unit tests for save/load/resume compatibility
Reports	Unit tests for output writers and file creation
Transports	Unit tests with mocked OpenVPN/WireGuard/process calls
Packaging	Installation smoke checks and runtime asset checks
Documentation	mkdocs build --strict

---

📚 Documentation changes

Update documentation when a change affects:

• CLI flags;
• config file options;
• reports;
• scan behavior;
• result buckets;
• installation;
• release process;
• Homebrew/pip packaging;
• transport setup;
• WAF/fingerprint/auto-calibration behavior.

Documentation lives in:

docs/

Build locally:

python -m mkdocs build --strict

Serve locally:

python -m mkdocs serve

Open:

http://127.0.0.1:8000/

---

📦 Packaging changes

If you change packaging metadata, runtime data files, entry points, dependencies, or install layout, run packaging checks.

Build:

python -m build

Install into a clean virtual environment:

python3 -m venv /tmp/opendoor-package-check
source /tmp/opendoor-package-check/bin/activate

python -m pip install --upgrade pip setuptools wheel
python -m pip install /path/to/OpenDoor/dist/opendoor-*.whl

opendoor --version
opendoor --help

Verify runtime assets:

python - <<'PY'
from pathlib import Path
import sys

root = Path(sys.prefix)

paths = [
    "opendoor.conf",
    "data/directories.dat",
    "data/subdomains.dat",
    "data/useragents.dat",
    "data/proxies.dat",
    "data/ignored.dat",
    "data/openvpn-profiles/example.ovpn",
    "data/wireguard-profiles/example.conf",
]

for rel in paths:
    print(rel, (root / rel).exists())
PY

All required runtime assets should exist.

---

🍺 Homebrew formula changes

When validating a Homebrew formula locally:

HOMEBREW_NO_INSTALL_FROM_API=1 brew install --build-from-source --verbose opendoor
HOMEBREW_NO_INSTALL_FROM_API=1 brew test opendoor
HOMEBREW_NO_INSTALL_FROM_API=1 brew audit --strict --new --online opendoor

A Homebrew test must not depend on external network access.

---

🔐 Secret hygiene

Before committing, check for accidental secrets.

Useful checks:

git grep -n -I -E '(BEGIN .*PRIVATE KEY|PrivateKey = [A-Za-z0-9+/=]{20,}|PresharedKey = [A-Za-z0-9+/=]{20,}|<key>|</key>)'

OpenVPN/WireGuard examples must contain placeholders only.

Do not commit:

• real VPN profiles;
• private keys;
• auth-user-pass files;
• cookies;
• API tokens;
• bearer tokens;
• customer target lists;
• generated reports with sensitive findings.

---

🧾 Pull request checklist

Before opening a pull request:

• [ ] The change is focused and reviewable.
• [ ] User-facing behavior is documented.
• [ ] Tests were added or updated where needed.
• [ ] python -m unittest passes.
• [ ] coverage report -m is acceptable.
• [ ] ruff check . passes.
• [ ] python -m mkdocs build --strict passes for docs changes.
• [ ] Packaging checks were run if install layout changed.
• [ ] No secrets or real transport profiles were committed.

---

🗂️ Commit message style

Use concise, descriptive commit messages.

Examples:

Add WAF summary to reports
Fix response size range filtering
Refresh ReadTheDocs usage guide
Include transport profile examples in package data

Avoid vague messages such as:

fix
updates
misc changes
work

---

🧯 Review guidance

When reviewing a contribution, check:

• whether the change matches the intended behavior;
• whether tests prove the new behavior;
• whether docs and examples are accurate;
• whether runtime defaults remain safe;
• whether package data is still included;
• whether the change introduces secret or credential risks;
• whether CI/CD behavior and exit codes remain predictable.

Prefer minimal, targeted fixes over broad rewrites.