mail-autodiscover

Repository on GitHub, which provides public git repositories with URLs.

Repository on GitHub, which uses git. git can track the changes, who made them, and when they were made.

Development happens in the open on the public repo, not only at release time. Between v0.3.3 and v0.4.0 alone main's history holds 131 interim commits. 88 pull requests have been merged (64 by the maintainer, 24 by Dependabot) through public PRs with required CI checks. Releases are just tags on this same history.

Repository on GitHub, which uses git. git is distributed.

Every release has a unique MAJOR.MINOR.PATCH identifier: pyproject.toml version, git tag vX.Y.Z and GitHub Release (13 releases, v0.1.0 to v0.4.1; at each tag pyproject.toml matches the tag and CHANGELOG.md has its heading). release.yml refuses to release if the tag already exists at a different commit. Container images carry the same X.Y.Z tag (GHCR from 0.2.1, Docker Hub from 0.4.0).

Releases use MAJOR.MINOR.PATCH versions (v0.1.0 through v0.4.1) as vX.Y.Z tags. release.yml rejects any pyproject.toml version that is not X.Y.Z with an optional pre-release suffix, i.e. the SemVer format. Container images use the same semver tags and SECURITY.md tells users to pin by semver tag or digest.

Every release is identified by a git tag: 13 vX.Y.Z tags (v0.1.0 to v0.4.1) on origin, one per GitHub Release, all reachable from main. The latest release (v0.4.1) was created by release.yml, which pins the tag to the exact merge commit; earlier tags predate that automation.

Non-trivial release notes file in repository: https://github.com/solarssk/mail-autodiscover/blob/main/CHANGELOG.md.

No publicly known run-time vulnerability with a CVE or similar ID has been reported in this project's own code: no published GitHub security advisories, none in the GitHub Advisory Database, and no CVE/GHSA IDs in CHANGELOG.md. CVEs Trivy raised against the Debian base image (OpenSSL) and pip are dependency issues, outside this criterion; the v0.4.1 notes mention the OpenSSL fix. Reports go through the private advisory route in SECURITY.md.

Non-trivial SECURITY[.md] file found file in repository: https://github.com/solarssk/mail-autodiscover/blob/main/SECURITY.md. [osps_do_02_01]

GitHub Issues is enabled and configured as the project's issue tracker: .github/ISSUE_TEMPLATE/bug_report.yml and feature_request.yml apply a 'type:' label automatically, and CONTRIBUTING.md ('Labels and milestones') defines the label taxonomy and the per-release vX.Y.Z milestones (13 milestones, v0.1.0 to v0.4.1) that issues and pull requests are tracked against.

No bug reports have been submitted, so none is left unacknowledged. The tracker has never held an issue (PR numbers 1-99 are contiguous, all authored by the maintainer or Dependabot) and the repository was created on 2026-06-10, so the whole 2-12 month window is covered and empty. The project is actively maintained: 13 releases, latest v0.4.1 on 2026-09-30.

No enhancement requests have been submitted (the tracker has never held an issue; feature_request.yml form is available), so none is left unanswered. The project is alive and still making changes: 13 releases since 2026-06-10, latest v0.4.1 on 2026-09-30.

Reports and responses are kept in the public GitHub issue tracker of this public repository: open and closed issues with all comments, plus pull request threads, are readable and filterable by anyone without an account. Discussions is disabled, so Issues and PRs are the archive. It is currently empty because no issues have been filed yet. https://github.com/solarssk/mail-autodiscover/issues

SECURITY.md, section 'Vulnerability disclosure' (also shown on the repo's Security policy page), publishes the process: open a private GitHub security advisory instead of a public issue and include a description, reproduction steps, impact and an optional fix. It states coordinated disclosure, a 48-hour acknowledgement target and a 14-day fix target for confirmed critical issues. README.md and CONTRIBUTING.md link to it. https://github.com/solarssk/mail-autodiscover/blob/main/SECURITY.md#vulnerability-disclosure

SECURITY.md tells reporters to use GitHub's private security advisory form (github.com/solarssk/mail-autodiscover/security/advisories/new), served over HTTPS and visible only to the repository maintainers and the reporter. Private vulnerability reporting is enabled on the repository. .github/ISSUE_TEMPLATE/config.yml also links it from the New issue page and disables blank public issues. https://github.com/solarssk/mail-autodiscover/blob/main/SECURITY.md#vulnerability-disclosure

No vulnerability reports have been received in the last 6 months (the repository itself dates from 2026-06-10): the security advisories list is empty in every state (triage, draft, published, closed), there are no issues, and the only published reporting channel is private vulnerability reporting (SECURITY.md). SECURITY.md sets a 48-hour acknowledgement target for when one arrives.

The deliverable is a container image. The Dockerfile builds it from source (pip install --require-hashes -r requirements.txt, then pip install --no-deps . via the hatchling backend in pyproject.toml); docker-compose.yml uses 'build: .'. CI rebuilds it on every PR and push (ci.yml job 'Docker build and scan', a required check) and docker-publish.yml builds the multi-arch (amd64/arm64) release images.

Standard tooling for this ecosystem: Docker (Dockerfile, docker build, docker compose) for the image, and pip with the PEP 517 hatchling backend declared in pyproject.toml [build-system] for the Python package. Runtime dependencies are locked with pip-compile (hash-pinned requirements.txt).

Everything needed to build is FLOSS: Docker Engine/BuildKit (Apache-2.0), CPython, the python:3.14-slim-bookworm (Debian) base image, pip, hatchling and pip-tools. No proprietary compiler or SDK is required; 'docker build .' rebuilds the image locally or in CI, and 'pip install .' builds the package.

pytest (MIT) suite in tests/: 141 test functions in 17 test_*.py files, released with the repo under MIT. How to run: README 'Development' and CONTRIBUTING.md step 4 (./scripts/check.sh), plain 'pytest' in AGENTS.md 'Running checks', and the CI script: ci.yml job 'Tests and coverage' runs 'pytest -v' and is a required check on main. Settings: pyproject.toml [tool.pytest.ini_options].

Standard Python invocation: plain 'pytest' from the repo root needs no arguments, because pyproject.toml [tool.pytest.ini_options] sets testpaths, pythonpath and coverage addopts. CI runs 'pytest -v'; scripts/check.sh, the pre-commit hook and the Python 3.14 compat job run 'pytest -q'.

Branch coverage is on (pyproject.toml [tool.coverage.run] branch = true) and pytest fails below 90% on app/ (--cov-fail-under=90). Codecov reports 97.15% for app/ (667 lines, 98 branches; app.codecov.io/gh/solarssk/mail-autodiscover). Tests cover Outlook, Thunderbird and Apple Mail, config/production validation, proxy-header trust, security headers, rate limiting and the no-mailbox-enumeration invariant.

ci.yml runs the test suite (job 'Tests and coverage', plus 'Compatibility tests (Python 3.14)') on every pull request and every push to main. Branch protection on main requires 'Tests and coverage', ruff, mypy, bandit + pip-audit and the Docker build to pass before merge, with enforce_admins on. The last 30 runs of ci.yml on main all succeeded.

CONTRIBUTING.md (Workflow, step 2) tells contributors to add tests where relevant, and .github/pull_request_template.md has the checklist item 'Tests added or updated (if behaviour changed)'. A 90% coverage gate on app/ (pyproject.toml addopts) and the required 'Tests and coverage' check back this up in CI.

Recent functional changes shipped with tests in the same PR: O(1) rate-limiter eviction (PR #53, tests/test_security.py); streaming body-size limit and mailbox-enumeration regression tests (PR #35, tests/test_no_mailbox_enumeration.py); log-injection and security-header fixes (0.3.2); forwarded-IP hardening (0.3.1). 0.4.1 was CI/build-only; its one new script (PR #80) came with tests/test_check_pr_docs_impact.py.

The policy is in the change-proposal instructions: CONTRIBUTING.md Workflow step 2 ('add tests where relevant') and the pull request template's checklist item 'Tests added or updated (if behaviour changed)' in .github/pull_request_template.md, which GitHub uses as the default description for new PRs.

Linters run in CI: ruff ('ruff check .', rules E, F, I, UP, B, SIM in pyproject.toml), mypy in strict mode on app/, and bandit (-r app -ll), plus CodeQL (security-extended) and SonarCloud. ruff and mypy also run in pre-commit; bandit is in scripts/check.sh. Lint (ruff), Type check (mypy) and Security (bandit + pip-audit) are required status checks on main.

Warnings fail the build: 'ruff check .', 'mypy app' and 'bandit -r app -ll' must pass in required CI checks before merge, and the last 30 CI runs on main are green. app/, scripts/ and tests/ contain no '# noqa' or '# nosec'; app/ has three narrowly-coded '# type: ignore[...]' comments (two untyped imports, one arg-type). GitHub code scanning shows 0 open alerts (64 total, all fixed).

mypy runs in strict mode and ruff lints the whole repo in CI, and pytest treats every warning as an error (filterwarnings = ["error"] in pyproject.toml), so a new deprecation from a dependency fails the run instead of scrolling past. The suite currently emits zero warnings on Python 3.12 and 3.14. https://github.com/solarssk/mail-autodiscover/blob/main/pyproject.toml

The sole maintainer built and documents the service on these principles: no database, admin panel or mailbox lookup (economy of mechanism); TRUST_PROXY_HEADERS=false plus refuse-to-start production validation (fail-safe defaults); one SecurityMiddleware on every request (mediation); non-root container (least privilege); a short listed endpoint set, docs/openapi off (attack surface); allowlist validation of addresses and domains. See SECURITY.md.

SECURITY.md 'Main risks and mitigations' names the error classes for this kind of service and a countermeasure for each: XXE/entity expansion (defusedxml), oversized-body DoS (streamed 413 cap), log injection (sanitised request ID and path), client-IP spoofing (forwarded headers honoured only from trusted proxies), XML injection (html.escape), mailbox enumeration (identical response shape). Covered by tests in tests/.

The code uses only SHA-256 (a NIST-published algorithm) via Python's standard hashlib, in app/security.py hash_domain, as a truncated log correlation tag, plus stdlib uuid for identifiers. It implements no cipher, protocol or key handling of its own. TLS is not done by this service: the container serves plain HTTP and SECURITY.md requires an HTTPS reverse proxy in front.

The only cryptographic call is hashlib.sha256 from the Python standard library (app/security.py); identifiers use stdlib uuid. Nothing is re-implemented in the repo, and TLS is left to the operator's reverse proxy (nginx, Caddy, etc.), not to project code.

The only cryptography-dependent code is Python-standard-library hashlib/uuid, which is FLOSS. HTTPS is provided by the operator's reverse proxy; the repo's nginx and Caddy guides describe HTTPS termination with nginx and Caddy, both FLOSS. No feature requires a proprietary crypto component.

N/A: the service holds no cryptographic keys and terminates no TLS itself (the container CMD runs plain-HTTP uvicorn; HTTPS and its key sizes are set on the operator's reverse proxy, per SECURITY.md). The only hash is SHA-256 in app/security.py, truncated to 12 hex chars purely as a log correlation tag; it protects no secret and is not used for authentication, integrity or confidentiality.

The only cryptographic primitive is SHA-256 (not broken) via Python's hashlib in app/security.py, used for a truncated log-correlation tag. No default security mechanism depends on a broken algorithm. TLS is terminated by the operator's reverse proxy, not by this project.

No security mechanism depends on an algorithm with known serious weaknesses. Disclosure: uuid.uuid5() (SHA-1 based, RFC 9562) derives stable Apple profile PayloadUUIDs in app/mobileconfig.py; these are identifiers only, not authentication, integrity or confidentiality.

N/A: the service performs no key agreement or session-key derivation. It serves plain HTTP inside the container, and SECURITY.md requires TLS termination at the operator's reverse proxy, so cipher suites and forward secrecy are configured there, not in this project's code.

N/A: the service has no user authentication and stores no passwords. README states it never stores, manages or sees mailbox passwords, and generated Apple profiles contain none (asserted in tests/test_mobileconfig.py). Clients authenticate directly to the operator's IMAP/SMTP server.

N/A: the service generates no cryptographic keys or nonces. Its only random values are uuid4 request-correlation IDs (app/security.py), which Python derives from os.urandom anyway; the other UUIDs are deterministic uuid5 identifiers (app/mobileconfig.py).

Distribution channels use HTTPS exclusively. [osps_br_03_02]

No cryptographic hash is fetched over http. The only downloaded tools in CI (gitleaks in ci.yml, actionlint in lint-workflows.yml) come over https (curl --proto =https --tlsv1.2) and are checked against a SHA-256 committed in the workflow via sha256sum. The Docker base image is pinned by digest and requirements.txt installs with --require-hashes.

No known medium-or-higher vulnerability is unpatched: the Security tab (maintainer view) shows zero open Dependabot, code-scanning and secret-scanning alerts and no security advisories. All 64 past code-scanning alerts (CodeQL and Trivy, up to high) were fixed within about 3 hours. CI runs pip-audit and Trivy on every push and PR, Dependabot is enabled, and the public Scorecard reports 0 existing vulnerabilities.

SECURITY.md commits to acknowledging private reports within 48 hours and shipping a fix for a confirmed critical issue within 14 days. No critical vulnerability has been reported (zero advisories); the highest-severity findings so far, three high CodeQL alerts and three high Trivy alerts, were fixed in about an hour, and fixes ship as a new release.

No private credential is in the public repo. A gitleaks scan of the full history (195 commits, all refs) found nothing; ci.yml also runs gitleaks on each push and PR (scoped to that run's new commits). GitHub secret scanning with push protection is enabled, zero alerts. .env is gitignored, .env.example and config.example.yaml hold only example.com placeholders, and workflows read secrets from Actions secrets.

CodeQL (Python and GitHub Actions, security-extended queries) runs on every push to main, every PR and weekly (.github/workflows/codeql.yml). ci.yml also runs bandit -ll on app/ (required merge check), ruff and mypy --strict; SonarCloud scans too (non-blocking). All passed on the v0.4.1 release PR and release commit. Listed in SECURITY.md's controls table.

CodeQL runs the security-extended query suite (codeql.yml line 44) for Python and GitHub Actions, and bandit, a Python security linter (bandit -r app -ll in ci.yml), is a required check on every PR. Both target common CWE-style vulnerability classes; SonarCloud adds its own security rules. No nosec/lgtm suppressions in the repo.

No open findings: SonarCloud (public) shows 0 vulnerabilities and 0 security hotspots, and GitHub code scanning has 0 open alerts (maintainer-visible). The only CodeQL alerts ever raised (3, in tests/, false positives) were fixed in about an hour (v0.1.2, PR #8); 26 zizmor workflow findings, one high, were fixed in 0.4.1 (CHANGELOG.md). bandit -ll (medium+) gates every merge.

CodeQL runs on every push to main, every pull request and weekly (codeql.yml). bandit, ruff and mypy run on every push to main and every PR via ci.yml (required status checks on main); SonarCloud also scans each push/PR (non-blocking). OpenSSF Scorecard's SAST check reports a SAST tool runs on all commits (30 of 30 checked).

The pytest suite (141 tests, incl. XXE payloads, oversized bodies, log-injection and proxy-header cases) runs on every PR and push as the required 'Tests and coverage' check, with branch coverage on (branch = true in pyproject.toml) and --cov-fail-under=90. Measured branch coverage is 95.9% (SonarCloud, public), total 97.8%, above the 80% the criterion names.

The project's own code is pure Python, a memory-safe language; the repository has no C, C++ or other memory-unsafe source (only .py, config, docs and images). Native extensions such as uvloop or pydantic-core are third-party dependencies, not software produced by this project.

Dynamic analysis here is the pytest suite. It always runs with Python assertions enabled (nothing in CI, pyproject.toml, the Dockerfile or scripts uses -O, PYTHONOPTIMIZE or --assert=plain) and contains 292 assert statements, including the mailbox-enumeration invariant tests. app/ itself has only 3 asserts (type narrowing), so the assertions live mainly in the tests, not in a separate assertion-heavy build. https://github.com/solarssk/mail-autodiscover/tree/main/tests

The dynamic analysis is the pytest suite, a required merge check, so a failing test cannot reach main. It has not surfaced any medium-or-higher vulnerability, and none reported another way is open: the repository has zero GitHub issues and no published security advisories; private vulnerability reporting is enabled (SECURITY.md).