houndarr

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.

Every change lands on main as an individual pull request, so the repository
carries the full development history between releases rather than release
drops. Release tags point at commits that were already on main and visible
for review. 35 version tags to date.

https://github.com/av1155/houndarr/commits/main
https://github.com/av1155/houndarr/pulls?q=is%3Apr+is%3Amerged

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

Each release has a unique X.Y.Z identifier. The VERSION file is the single
source of truth, and a CI check blocks any pull request where VERSION and the
topmost CHANGELOG heading disagree. Each version ships as a git tag, a GitHub
Release, and matching GHCR image tags. Current release: 1.13.1.

https://github.com/av1155/houndarr/blob/main/VERSION
https://github.com/av1155/houndarr/releases

Every release is tagged in git as vX.Y.Z. Pushing the tag is what drives the
release: it triggers the multi-arch image build and push to GHCR, creates the
GitHub Release from the matching CHANGELOG block, and packages the Helm chart.

https://github.com/av1155/houndarr/tags

Non-trivial release notes file in repository: https://github.com/av1155/houndarr/blob/main/CHANGELOG.md.

Houndarr has had no publicly known vulnerabilities of its own, so there is
nothing of this kind to list. The changelog does name upstream CVEs by
identifier whenever a dependency bump clears one, for example the starlette
and python-multipart advisories cleared in 1.12.x, even though dependency
vulnerabilities fall outside this criterion.

https://github.com/av1155/houndarr/blob/main/CHANGELOG.md

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

GitHub Issues, with structured bug report and feature request forms. Every
issue carries a type label and a priority label, and an automation follows up
on issues waiting on the reporter so threads do not go silent.

https://github.com/av1155/houndarr/issues

24 issues were opened by people other than the maintainer over the last 12
months, and all 24 are closed. Every bug report got a reply in the thread.
Recent examples: #632, #586, #577, #385, #363, #343, #308, #309.

https://github.com/av1155/houndarr/issues?q=is%3Aissue+sort%3Acreated-desc

Feature requests get a reply and a stated outcome. Of the 11 opened by users
in the last 12 months, all 11 are closed with the decision visible in the
thread. Some were closed by shipping the feature, for example #619 landed in
pull request #624. Others were closed as duplicates or as out of scope, for
example #656.

https://github.com/av1155/houndarr/issues?q=is%3Aissue+label%3A%22type%3A+feature%22

All issue and pull request discussion is public, searchable through GitHub
search, and addressable by URL. Threads are locked after a long period of
inactivity but stay readable.

https://github.com/av1155/houndarr/issues?q=is%3Aissue

SECURITY.md documents the process: do not open a public issue, use GitHub's
private reporting flow, and include the affected version or commit, the
environment, reproduction steps, an impact assessment, and a proof of concept
if there is one. It also states the response expectations. The security pages
on the documentation site link to the same flow.

https://github.com/av1155/houndarr/blob/main/SECURITY.md
https://av1155.github.io/houndarr/docs/security/overview

Private vulnerability reporting is enabled on the repository, so reports go
through GitHub over HTTPS and stay private until an advisory is published.
The form is linked from SECURITY.md and from the security section of the
documentation site.

https://github.com/av1155/houndarr/security/advisories/new

No vulnerability reports have been received in the last 6 months, and no advisory has been published for the project. SECURITY.md commits to an initial acknowledgement within 72 hours.

A multi-stage Dockerfile builds the shipped artifact from source: a Node stage
compiles the Tailwind CSS bundle, and the runtime stage installs Python
dependencies from uv.lock. docker build . reproduces the published image, and
CI builds it on every pull request. Building outside Docker is documented as
uv sync, pnpm install --frozen-lockfile, pnpm run build-css, then
uv run houndarr.

https://github.com/av1155/houndarr/blob/main/Dockerfile
https://av1155.github.io/houndarr/docs/guides/installation/from-source

Docker with BuildKit for the image, uv for Python dependency resolution and environment creation, pnpm for the CSS build, and a justfile that wraps the gates, the test slices, and the dev server.

Every tool in the build path is FLOSS: Docker Engine and BuildKit, uv, Node.js, pnpm, CPython, and Tailwind CSS. Nothing proprietary is needed to build or run the project.

A pytest suite of 2806 tests lives in tests/ and is released under the same
AGPL-3.0 license as the rest of the repository. How to run it is documented in
CONTRIBUTING.md (uv run pytest) and in the justfile (just test,
just test-quick, just test-integration, just test-browser). CI runs it on
every pull request.

https://github.com/av1155/houndarr/tree/main/tests
https://github.com/av1155/houndarr/blob/main/CONTRIBUTING.md#required-local-checks

pytest is the standard invocation for Python. uv run pytest runs it against
the project environment, and just test is the repository shorthand.

Measured with pytest-cov and branch coverage enabled, the suite covers 92% of src/houndarr: 6012 statements with 355 missed, and 1384 branches with 133 partial. Coverage includes the auth middleware, the encryption layer, instance URL validation, and the search engine cycle.

Every pull request runs the full suite on Python 3.13 alongside lint, format,
type check, bandit, Trivy filesystem and image scans, CodeQL, a pip-audit
dependency audit, dependency review, and a live security smoke test against a
freshly built container. Merges are blocked until the required checks pass.

https://github.com/av1155/houndarr/tree/main/.github/workflows

Behaviour changes require test changes. CONTRIBUTING.md states it, and the
pull request template carries it as a checklist item: "Tests added/updated for
all changes".

https://github.com/av1155/houndarr/blob/main/CONTRIBUTING.md#pull-request-guidance

Recent pull requests that touched src/houndarr all shipped test changes with
them. Counts of source files against test files: #644 (29 / 25), #643
(17 / 17), #631 (15 / 11), #624 (10 / 9), #679 (7 / 5), #642 (4 / 3).

https://github.com/av1155/houndarr/pulls?q=is%3Apr+is%3Amerged

CONTRIBUTING.md tells contributors to implement changes with tests and to
update tests for behaviour changes, and the pull request template has a
checklist item for it.

https://github.com/av1155/houndarr/blob/main/CONTRIBUTING.md
https://github.com/av1155/houndarr/blob/main/.github/pull_request_template.md

Ruff runs with eleven rule families selected: pycodestyle E and W, pyflakes F,
isort I, bugbear B, comprehensions C4, pyupgrade UP, simplify SIM, annotations
ANN, bandit security S, and pep8-naming N. mypy runs in strict mode over src/.
hadolint checks the Dockerfile and actionlint checks the workflows. All are CI
gates.

https://github.com/av1155/houndarr/blob/main/pyproject.toml

The lint and type check jobs fail the build on any finding, so main stays clean. The few suppressions are narrow and each carries a comment explaining why: assert in tests, binding all interfaces for a self-hosted server, function calls in defaults for the FastAPI Depends pattern, and nested context managers that aiosqlite cannot combine.

mypy runs with strict = true plus warn_return_any, warn_unused_ignores,
warn_redundant_casts, disallow_untyped_defs, disallow_incomplete_defs, and
no_implicit_optional. Ruff's selection includes the bandit security rules
across the whole source tree, and the per-file relaxations are limited to the
test directory.

I am the sole maintainer and designed the security model. The principles show
up in specific decisions rather than as a claim.

Fail-safe defaults and complete mediation: one global authentication
middleware validates the session and CSRF token for every request, so a newly
added route is protected unless it is explicitly listed in a small
unauthenticated allowlist. There are no per-route auth decorators to forget.

Least privilege: the container drops to a non-root user after PUID/PGID
remapping. Calls to *arr instances are read-only apart from the search command
itself, and Houndarr holds no download client or indexer credentials.

Limited attack surface: no download client integration, no indexer access, no
request workflow, no media file manipulation. OpenAPI documentation is served
only when dev mode is on. Exactly one endpoint is authorized by the Houndarr
API key, and it is read-only.

Economy of mechanism: a single admin account, one authentication middleware,
one encryption path for stored credentials.

Open design: the encryption scheme, session handling, cookie flags, and the
trust boundary are published rather than kept quiet.

Input validation with allowlists: instance URLs are checked against an
allowlist of schemes and a hostname pattern, and both literal addresses and
DNS-resolved addresses are rejected when they land on loopback or link-local
ranges. Private LAN ranges are deliberately permitted because that is where
*arr instances live, and the reasoning is documented in the module.

Psychological acceptability: polite defaults out of the box, so an operator
who changes nothing cannot exhaust their indexer budget.

https://av1155.github.io/houndarr/docs/security/threat-model

Yes, for the classes that apply to a self-hosted Python web application.

SQL injection: all queries use parameterised aiosqlite statements.
XSS: Jinja2 autoescaping, with no raw rendering of user-supplied values.
CSRF: a signed double-submit token validated in middleware with a constant-time
comparison.
Missing authentication and authorization: enforced globally in middleware, so
protection is the default state for a route.
SSRF: scheme allowlisting plus post-resolution address checks on configured
instance URLs.
Credential exposure: instance API keys are encrypted at rest and never sent
back to the browser; Houndarr API keys are stored as SHA-256 digests of
256-bit random tokens.
Brute force: per-IP login rate limiting, with bucket eviction so the limiter
cannot grow without bound.
Header spoofing: proxy auth trusts forwarded headers only from configured
trusted proxy ranges, and dispatch and validation share one code path.
Vulnerable dependencies: pip-audit, Trivy, CodeQL, and Dependabot.

tests/test_huntarr_vulns.py runs 63 cases derived from a published security
review of a comparable tool, covering unauthenticated access to every
protected route, secret leakage in response bodies, and setup lockout after
first run.

https://av1155.github.io/houndarr/docs/security/audit

Only published, reviewed primitives. Instance API keys are encrypted at rest
with Fernet from pyca/cryptography, which is AES-128 in CBC mode with
HMAC-SHA256 for integrity. The admin password is hashed with bcrypt. Session
cookies are signed with HMAC-SHA256 through itsdangerous. Houndarr API keys
are 256-bit random tokens stored as SHA-256 digests.

https://av1155.github.io/houndarr/docs/security/credential-handling

Houndarr implements no cryptography of its own. It calls pyca/cryptography for Fernet, the bcrypt package for password hashing, itsdangerous for cookie signing, and the Python standard library's secrets, hmac, and hashlib for token generation and constant-time comparison.

Every cryptographic dependency is FLOSS: pyca/cryptography (Apache-2.0 or BSD-3-Clause), bcrypt (Apache-2.0), itsdangerous (BSD-3-Clause), and the Python standard library, with OpenSSL underneath.

Defaults exceed the NIST through-2030 minimums and there is no setting that
lowers them. The Fernet master key is 256 bits from Fernet.generate_key(),
which draws from os.urandom(32), and splits into a 128-bit AES key and a
256-bit HMAC-SHA256 key. The session signing secret is 256 bits from
os.urandom(32). CSRF tokens are 256 bits from secrets.token_hex(32). Houndarr
API keys are 256 bits from secrets.token_urlsafe(32). Password hashing uses
bcrypt at cost factor 12.

No broken algorithm appears anywhere in the codebase: no MD4, MD5, SHA-1, single DES, RC4, or ECB mode. Fernet's CBC mode is paired with HMAC-SHA256 in an encrypt-then-MAC construction, so ciphertext is authenticated before decryption. SHA-256 appears only as a lookup digest for API key tokens that are already 256 bits of CSPRNG output, where password-style stretching would add nothing.

No SHA-1 and no unauthenticated cipher modes. Hashing is SHA-256 or stronger, symmetric encryption is authenticated, and password storage uses bcrypt rather than a fast hash.

Houndarr implements no key agreement protocol. Inbound TLS is terminated by
the operator's reverse proxy, and outbound calls to *arr instances use the
platform TLS stack through httpx. Forward secrecy is a property of those
layers rather than of anything this project implements.

The admin password is stored as a bcrypt hash at cost factor 12 with a
per-hash salt from bcrypt.gensalt(). Plaintext is never written to the
database or to logs. In proxy auth mode no password is stored at all.

https://av1155.github.io/houndarr/docs/security/credential-handling

All keys, tokens, and nonces come from the operating system CSPRNG: os.urandom for the Fernet master key and the session signing secret, and the secrets module for CSRF tokens and Houndarr API keys. The random module appears only in search scheduling and ordering jitter, which has no security role, and those call sites are annotated as such.

Distribution channels use HTTPS exclusively. [osps_br_03_02]

Nothing is fetched over plain HTTP. Python dependencies install from uv.lock, which records a hash for every artifact, over HTTPS from PyPI. The CSS build uses pnpm with a lockfile carrying integrity hashes. Every GitHub Action is pinned to a full 40-character commit SHA, with a CI check that enforces the pinning. Container images move over HTTPS to and from GHCR.

No vulnerability has been reported against Houndarr and none is publicly known. Dependency advisories surfaced by pip-audit, Trivy, CodeQL, or Dependabot are patched well inside 60 days, usually within the same week, and the changelog records which advisory each bump clears. The repository currently has no open code scanning alerts and no open Dependabot alerts.

Critical advisories are patched and released as soon as an upstream fix exists. The security workflow runs on every pull request, on a weekly schedule, and on manual dispatch, so a fix does not have to wait for the next pull request to be picked up.

No credential is committed. The Fernet master key, the session signing secret, and the SQLite database are generated at runtime inside the operator's data directory, which is gitignored along with .env files. GitHub secret scanning and push protection are both enabled on the repository. Test fixtures use throwaway values.

Several tools run beyond the linter and type checker. CodeQL default setup
analyses Python, JavaScript, TypeScript, and Actions on every push to main,
every pull request, and weekly. bandit runs against src/ on every pull
request. Trivy scans both the filesystem and the built container image.
pip-audit checks the dependency set generated from uv.lock, and GitHub
dependency review runs on pull requests.

https://github.com/av1155/houndarr/blob/main/.github/workflows/security.yml

CodeQL's default query suite and bandit are both built to find common vulnerability patterns: injection, unsafe deserialization, weak hashing, hardcoded credentials, and path traversal. Trivy adds known-CVE detection across dependencies and image layers, with results uploaded to the GitHub security tab.

The repository has no open code scanning alerts and no open Dependabot alerts. Findings get fixed rather than dismissed. Where a rule fires on intentional behaviour, the suppression is inline and carries the reason, for example the bind-all-interfaces rule on a server meant to be reachable from the LAN.

CodeQL runs on every push to main, on every pull request, and on a weekly schedule. bandit, Trivy, and pip-audit run on every pull request and weekly.

The automated suite is 2806 tests covering 92% of src/houndarr with branch
coverage enabled, above the 80% branch coverage this criterion accepts.
Separately, every pull request builds the container image, starts it, creates
an account, and runs a smoke test that varies inputs against the live
instance: an unauthenticated sweep of every protected route, path traversal
attempts, X-Forwarded-For spoofing against the proxy auth gate, CSRF omission
on admin endpoints, and login rate limiting. A Playwright job drives the real
UI in a browser against the same stack.

https://github.com/av1155/houndarr/blob/main/scripts/security_smoke_test.sh

The project produces no code in a memory-unsafe language. It is Python, Jinja2 templates, CSS, and a small amount of browser JavaScript.