pcmt

Password Compromise Monitoring Tool

🚧 note: this project is being developed as a part of my thesis and is currently a work in progress. 🚧

pcmt Gopher logo based on the Egon Elbre's awesome Gopher designs.

Who is this good for

it might come in handy to anybody willing to operate this application for family, a group of friends, a university faculty or even just for themselves.

What even is this

Password Compromise Monitoring Tool offers a frictionless way to check credentials for potential compromise. of course, the application cannot possibly know it all, which is why no indication of compromise does not necessarily amount to no compromise.

How to try this out

with podman and just installed, run the following, only supplanting the mt-pcmt:<tag> with either testbuild or one of the recent tagged releases:

# build the image locally using kaniko.
just kaniko

# start postgres.
just dbstart

# in another terminal, run the application.
# LiveMode=False disables loading assets and templates from the filesystem and
# instead uses the embedded resources.
podman run --rm -it -e PCMT_DBTYPE=postgres \
    -e PCMT_CONNSTRING="host=127.0.0.1 port=5432 sslmode=disable dbname=postgres password=postgres"
    -e PCMT_LIVE=False docker.io/immawanderer/mt-pcmt:<tag> \
    -config /etc/pcmt/config.dhall

while the above runs fine, running in pods is better and more close to a production setting (assuming rootless Podman setup):

# create a pod 🦭.
podman pod create --userns=keep-id -p3005:3000 --name pcmt

# if you have the db from the previous example still running, terminate it by
# pressing ^C or running the following:
just dbstop

# run a db in the pod.
podman run --pod pcmt --replace -d --name "pcmt-pg" --rm \
    -e POSTGRES_INITDB_ARGS="--auth-host=scram-sha-256 --auth-local=scram-sha-256" \
    -e POSTGRES_PASSWORD=postgres -v $PWD/tmp/db:/var/lib/postgresql/data \
    docker.io/library/postgres:15.3-alpine3.18

# run the application in the pod (assuming that you have built it as in the
# previous example). do note that we're connecting to the db using its
# container name, while localhost would also work. inside the pod, every
# container is reachable on localhost.
podman run --pod pcmt --replace --name pcmt-og -d --rm \
    -e PCMT_LIVE=False \
    -e PCMT_DBTYPE="postgres" \
    -e PCMT_CONNSTRING="host=pcmt-pg port=5432 sslmode=disable user=postgres dbname=postgres password=postgres" \
    -v $PWD/config.dhall:/config.dhall:ro \
    docker.io/immawanderer/mt-pcmt:<tag> -config /config.dhall

# also, if we try to connect to the db from the host we get an error (unless
# there is another database running on localhost already, such as the one from
# the previous example).

curl localhost:5432
--> curl: (7) Failed to connect to localhost port 5432 after 0 ms: Couldn't connect to server

# that is because the database port has not been exposed from the pod (recall
# the pod creation command).

Custom config

Make sure to check out the Dhall configuration schema to see what's possible, or have a look at the example config.

If you're new to Dhall, its documentation page is a good resource to start at.

Run modes

there are toggles that affect how the application behaves, and they can both be supplied either as environment variables prefixed with PCMT_ or in the configuration file:

• LiveMode
• DevelMode

live mode makes the application load all assets from persistent storage, i.e. it no assets embedded at build time are used (so make sure to supply your own).

devel mode is mainly useful in development or when debugging. it makes the application reload the templates at every request and automatically increases log levels.

🔨 Building from sources

pre-requisites:

• just (for convenience)
• npm
• go1.20
• git

the application consists of frontend and backend. the frontend is basically a generated TailwindCSS stylesheet and it is not shipped as part of the development process. as such, it needs to be built from sources just the same as the backend.

step 0: clone this repository with git

step 1: build the frontend using just tw or just frontend

step 2: finally, build the Go application using:

# debugging version.
just build

# or with debugging information stripped.
just buildrelease

step 1-alt: build both frontend and backend in release modes using: just prod.

the order of the steps is important as the application embeds the generated stylesheet.

if you plan to run the application in LiveMode, the stylesheet can be supplied when running the application; however, the binary will lack the way to fall back to the embedded asset so bear that in mind.

if you're curious, you can open the justfile to see the details of the build targets (such as tw and buildrelease) used above.

⚖️ LICENSE

AGPL-3.0-only (see LICENSE for details).