Argus

Keeping an eye on releases.

Argus will query websites at a user defined interval for new software releases and then trigger Gotify/Slack/Other notification(s) and/or Webhook(s) when one has been found. For example, you could set it to monitor the Argus repo (release-argus/Argus). This will query the GitHub API and track the "tag_name" variable. When this variable changes from what it was on a previous query, a GitHub-style Webhook could be sent that triggers something (like AWX) to update Argus on your server.

Table of Contents

• Demo
• Command-line arguments
• Authentication
• Building from source
  • Prerequisites
  • Go changes
  • React changes
• Getting started
  • Config formatting

Demo

A demo of Argus can be seen on our website here.

Command-line arguments

$ argus -h
Usage of /usr/local/bin/argus:
  -auth.create-admin string
        Username of the first administrator to create at startup (a password is generated and printed to stdout); only valid before any account exists
  -auth.reset-password string
        Username whose password to reset at startup (a new password is generated and printed to stdout); their sessions are revoked, but their API tokens are unchanged
  -config.check
        Print the fully-parsed config.
  -config.file string
        Argus configuration file path (env_var=ARGUS_CONFIG_FILE) (default "config.yml")
  -data.database-file string
        Database file path (env_var=ARGUS_DATA_DATABASE_FILE) (default "data/argus.db")
  -data.readonly
        Disable persisting config changes back to the config file (env_var=ARGUS_DATA_READONLY)
  -log.level string
        ERROR, WARN, INFO, VERBOSE or DEBUG (env_var=ARGUS_LOG_LEVEL) (default "INFO")
  -log.timestamps
        Enable timestamps in CLI output (env_var=ARGUS_LOG_TIMESTAMPS)
  -test.commands commands
        Put the name of the Service to test the commands of.
  -test.notify string
        Put the name of the Notify service to send a test message.
  -test.service string
        Put the name of the Service to test the version query.
  -web.basic-auth.password string
        Password for basic auth (env_var=ARGUS_WEB_BASIC_AUTH_PASSWORD)
  -web.basic-auth.username string
        Username for basic auth (env_var=ARGUS_WEB_BASIC_AUTH_USERNAME)
  -web.cert-file string
        HTTPS certificate file path (env_var=ARGUS_WEB_CERT_FILE)
  -web.listen-host string
        IP address to listen on for UI, API, and telemetry (env_var=ARGUS_WEB_LISTEN_HOST) (default "0.0.0.0")
  -web.listen-port string
        Port to listen on for UI, API, and telemetry (env_var=ARGUS_WEB_LISTEN_PORT) (default "8080")
  -web.pkey-file string
        HTTPS private key file path (env_var=ARGUS_WEB_PKEY_FILE)
  -web.route-prefix string
        Prefix for web endpoints (env_var=ARGUS_WEB_ROUTE_PREFIX) (default "/")

Authentication

Argus can require a login for the web UI and API. It is disabled by default, so an existing config.yml keeps working unchanged on upgrade.

settings:
  auth:
    enabled: true # ARGUS_AUTH_ENABLED
    local:
      enabled: true # ARGUS_AUTH_LOCAL_ENABLED - username/password logins.
    session:
      lifetime: 720h # ARGUS_AUTH_SESSION_LIFETIME - absolute cap.
      idle_timeout: 168h # ARGUS_AUTH_SESSION_IDLE_TIMEOUT - sliding window.
      max_per_user: 10 # ARGUS_AUTH_SESSION_MAX_PER_USER - concurrent sessions.
      secure_cookie: true # ARGUS_AUTH_SESSION_SECURE_COOKIE - override the cookie's Secure attribute.
  web:
    trusted_proxies: # ARGUS_WEB_TRUSTED_PROXIES - IPs/CIDRs whose forwarded headers are trusted.
      - 10.0.0.1

Notes:

• settings.auth and settings.web.basic_auth are mutually exclusive.
• The first administrator is created through the UI's first-run setup page, which is reachable without credentials until an account exists. Complete setup before exposing a freshly auth-enabled instance to an untrusted network, or create the account up front with argus -auth.create-admin <username>. It generates a password, prints it to stdout and exits, so setup is already closed by the time the server accepts connections.
• API tokens cannot create or revoke API tokens; token management needs a browser session.
• Locked out? argus -auth.reset-password <username> generates a new password, prints it to stdout and revokes that user's sessions (their API tokens are left intact).
• With auth on, RBAC grants govern access. /metrics and /api/v1/counts require metric:read, so Prometheus scrapers and Heimdall need a token with that permission.
• Behind a reverse proxy, set trusted_proxies: X-Forwarded-For and X-Forwarded-Host are ignored otherwise, and the client IP used for rate limiting and logging falls back to the peer address. X-Forwarded-Proto: https is honoured from any peer, so the session cookie is marked Secure even before trusted_proxies is set; a proxy that omits it needs auth.session.secure_cookie: true.

Building from source

Prerequisites

The backend of Argus is built with Go, and the frontend with React. The React frontend is built and then embedded into the Go binary so that those web files can be served.

• Go 1.25+
• NodeJS 24

Go changes

To see the changes you've made by modifying any of the .go files, you must compile Argus. Run make build the first time to ensure the web components are available locally. Any future builds that don't need the web-ui to be rebuilt can be done with make go-build (faster than make build). Running either of these in the root dir will produce an argus binary.

React changes

To see the changes after modifying anything in web/ui/react-app, you must recompile both the Go backend and the React frontend. This can be done by running make build. Running this in the root dir will produce the argus binary.

Getting started

To get started with Argus, simply download the binary from the releases page, and set up the config for that binary.

For further help, check out the Getting Started page on our website.

Config formatting

The config can be broken down into 5 key areas. (Further help)

• defaults - This is broken down into areas with defaults for services, notify and webhooks.
• settings - Settings for the Argus server.
• service - A dictionary mapping of all the services to monitor as well as what to notify when a new release is found.
• notify - A dictionary mapping of targets for Notify messages.
• webhook - A dictionary mapping of targets for Webhooks.