securo - Moses Yebei

The Problem

People who want a self‑hosted finance manager must choose between brittle home‑grown scripts and SaaS products that hoard every transaction. The result is either a maintenance nightmare or a privacy loss.

What This Does

securo delivers a full‑stack personal finance platform that runs entirely on your own infrastructure. The backend lives in backend/ (Python, FastAPI, Alembic migrations) and exposes a REST API via the entry points backend/app/main.py and backend/app/api/setup.py. The frontend in frontend/ is a React/TypeScript SPA built with npm (frontend/package.json). Docker and Docker‑Compose files (backend/Dockerfile, frontend/Dockerfile, docker‑compose.yml) orchestrate the two services together with a PostgreSQL container (implicit in the compose file). Optional AI agents are implemented under backend/app/agents/, exposing LLM‑driven endpoints that can query your financial data.

How It Is Wired

Container start – docker-compose.yml builds the backend image from backend/Dockerfile. The Dockerfile runs uvicorn backend.app.main:app --host 0.0.0.0 --port 8000.
FastAPI boot – backend/app/main.py creates the FastAPI instance, loads configuration from backend/app/core/config.py, and includes routers from every backend/app/api/*.py module (e.g., accounts.py, transactions.py, budget.py).
Request flow – An HTTP request hits a router (e.g., GET /api/transactions). The router function in backend/app/api/transactions.py validates the request, then calls service functions in backend/app/core/ or backend/app/agents/services/ as needed.
Database interaction – All persistence uses SQLAlchemy sessions created in backend/app/core/database.py. Alembic migration scripts (backend/alembic/versions/*.py) define the schema evolution.
Auth & rate‑limit – Middleware in backend/app/core/auth.py and backend/app/core/rate_limit.py enforce JWT/TOTP/OIDC flows defined in backend/app/api/custom_auth.py and backend/app/api/oidc_auth.py.
Agent path – Calls to /api/agents/* are routed to backend/app/agents/api/*.py. The request ultimately reaches a provider implementation in backend/app/agents/providers/ (e.g., openai.py, anthropic.py). The provider returns a response that backend/app/agents/runtime/executor.py formats back to the client.
Frontend – frontend/Dockerfile runs npm ci && npm run build, producing static assets served by the backend or a separate Nginx container (depending on compose overrides). The SPA talks to the API at /api/ using the OpenAPI spec generated by FastAPI.

The widest blast‑radius lies in backend/app/main.py (initializes the whole API) and backend/app/core/database.py (shared DB session). The agents subsystem introduces a modest cycle: provider ↔ runtime ↔ service, but it is isolated behind its own router.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/securo.git
cd securo

# Copy example env files and edit as needed
cp .env.example .env
cp backend/.env.example backend/.env

# Build and start all services (Docker Desktop, Docker or Podman required)
docker compose up --build

The README’s quick‑start script (curl … | bash) performs the same steps automatically. After the containers are healthy, open http://localhost:3000. The frontend will prompt for account creation; the backend will store data in the attached PostgreSQL container.

Real‑World Use

A small business owner can add a European bank by setting the ENABLE_BANKING_CLIENT_ID and ENABLE_BANKING_CLIENT_SECRET variables in backend/.env, restart docker compose, then create a “Bank Sync” job through the UI. The sync task calls backend/app/api/connections.py → backend/app/core/database.py to persist fetched transactions, which are immediately visible in the SPA’s Net‑Worth report.

Code Health & Issues

Low – No structural red flags – tests (208 files), CI workflow (.github/workflows/ci.yml), lockfiles, and license are present.
Low – Large migration history – 71 Alembic revisions (backend/alembic/versions/) may slow fresh DB setup; consider squashing older migrations.
Medium – Optional agent dependencies – AI provider packages are imported lazily but still increase the Docker image size; a separate build target could isolate them.

The Bottom Line

securo is a well‑organized, fully containerized finance manager with a clear API boundary and solid test/CI coverage. It is ready for teams that need on‑prem privacy and are comfortable maintaining Docker‑based services. The main trade‑off is the sizeable migration set and optional AI agent overhead, which may require pruning for lightweight deployments.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

875 files

Python443
TSX159
TypeScript87
TOML49
YAML36
JSON21

ReactDjangoExpressDockerKubernetes

Module dependencies

The 10 most depended-upon modules of 690, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_frontend_src_types_index["index"] n1_rontend_src_lib_country_flag["country-flag"] n2_rontend_src_lib_country_name["country-name"] n3_frontend_src_lib_modules["modules"] n4_ntend_src_lib_tax_id_country["tax-id-country"] n5_src_lib_account_detail_utils["account-detail-utils"] n6_nd_src_lib_calendar_activity["calendar-activity"] n7_lib_category_selection_utils["category-selection-utils"] n8_d_src_lib_installment_series["installment-series"] n9_frontend_src_lib_nav_items["nav-items"] n5_src_lib_account_detail_utils --> n0_frontend_src_types_index n6_nd_src_lib_calendar_activity --> n0_frontend_src_types_index n7_lib_category_selection_utils --> n0_frontend_src_types_index n8_d_src_lib_installment_series --> n0_frontend_src_types_index n9_frontend_src_lib_nav_items --> n3_frontend_src_lib_modules n4_ntend_src_lib_tax_id_country --> n1_rontend_src_lib_country_flag n4_ntend_src_lib_tax_id_country --> n2_rontend_src_lib_country_name

Dependencies

14 of 76 declared dependencies are a major version behind. Resolved 75 of 76 against the registry.

Package	Declared	Latest	Behind
`cryptography`	==46.0.7	50.0.0	4 major
`redis`	>=5.0.0	8.1.0	3 major
`fastapi-users`	>=13.0.0	15.0.5	2 major
`@types/node`	^24.10.13	26.2.0	2 major
`typescript`	~5.9.3	7.0.2	2 major
`aiofiles`	>=24.0	25.1.0	1 major
`webauthn`	>=2.8.0	3.0.0	1 major
`pypdf`	>=5.0.0	6.16.1	1 major

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high3

medium5

low1

Pin third-party GitHub Actions to a commit SHAhigh8 occurrences

.github/workflows

schneegans/dynamic-badges-action@v1.9.0, azure/setup-helm@v5, docker/setup-buildx-action@v4, docker/login-action@v4

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Upgrade the pinned dependency carrying a published advisoryhigh7 occurrences

cryptography@46.0.7 GHSA-537c-gmf6-5ccf (high) +6 more

The pinned version is the one that installs, so a published advisory against it describes this deployment rather than a hypothetical one, and the advisory is also a public description of how to exploit it.

Fix: Upgrade to the fixed version named in the advisory, then commit the lockfile.

Open a pull request instead of pushing to the default branchhigh

.github/workflows/prepare-release.yml

git push origin --delete $BRANCH"

Automated commits land on the branch that deploys, with no test having run against the result.

Fix: Push to a bot branch and open a pull request, or restrict the push to a tag ref.

Declare least-privilege permissions for GITHUB_TOKENmedium2 occurrences

.github/workflows/ci.yml

2 workflow(s) declare no permissions, 2 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Pin the container base image by digestmedium

backend/Dockerfile

python:3.14-slim

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/ci.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Add a non-root USER to the imagemedium

backend/Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/ci.yml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.