Introduction

!!! Note:
!!! Development is in very early stages, targeting documentation first.
!!! There is no working code here yet.

This is the README for puca ("Pan-Unix Control Agent"), an endpoint management tool for Unix-like systems which needs no inbound connectivity to the endpoints.

The agent, puca, runs on each system being managed, and connects to a central pucamgr instance to retrieve instructions and send responses.

From the central manager, an operator can see the following for all endpoints, or subsets of endpoints:

• Patching and service status (via the uact tool)
• Security baseline compliance status (via the xyz tool)
• Scheduled command status and logs (via the scw tool)
• Operating system and hardware type
• Currently active and pending actions

The operator can search for endpoints and add them to groups, according to arbitrary criteria, using a simple query language.

Operators can queue up actions for endpoints to run. Actions are retrieved by each endpoint's puca agent and executed by calls to the external tools uact, xyz, and scw. This allows the operator to:

• Install, update, and remove packages
• Apply security baseline compliance remediations
• Manage security check exceptions
• Start, stop, enable, and disable services
• Enable, disable, and re-run scheduled tasks under scw
• Delegate specific pre-prepared actions to other operators

Both the agent and the central manager produce metrics which can be collected by monitoring tools such as Zabbix, Prometheus, and so on, allowing alerts about endpoint status to be tailored to the local norms.

Endpoint registration policy is flexible - pucamgr can impliticly trust all new puca agents, or require operators to approve new agents, or trust agents that use a pre-registered public key, or use a pre-shared secret, or restrict by IP address. These can be combined arbitrarily, so for example operator approval can be required for agents from one subnet, while trusting agents using a pre-shared key from another subnet.

Documentation

Manual pages are included in this distribution - "man puca" for the endpoint agent, and "man pucamgr" for the manager. Before installation, these are in "agent/docs/puca.8" and "manager/docs/pucamgr.8".

Changes are listed in "docs/NEWS.md".

See "docs/DEVELOPERS.md" for development and translation notes.

Installation

There are two components to this project:

• puca - the agent, to be installed on every managed endpoint;
• pucamgr - the central management system.

Before beginning the installation process, decide whether to build the agent, the central manager, or both.

• "sh ./configure --disable-manager" for just the agent;
• "sh ./configure --disable-agent" for just the manager;
• "sh ./configure" to build both.

This will generate a Makefile for your system. Typing "make" will then build the selected components, and "make install" will install them.

For example, building and installing both components is done like this:

sh ./configure --prefix=/usr
make
sudo make install

See "docs/INSTALL" for more about the configure script.

Installing from the repository

If this is not a packaged release, the configure script is not included. It is generated with the GNU build system tools (autoconf, aclocal, autopoint, automake), plus gettext and pkg-config. On Debian or Ubuntu, run "sudo apt install automake autopoint gettext pkg-config". Once those tools are in place, call "autoreconf -is" to generate the configure script, and run it as described above.

Dependencies

To build the agent, these libraries are required:

• libcurl - for network transfers;
• Jansson - to handle JSON data.

To run the agent, each endpoint will need the libcurl and Jansson libraries installed, as well as these tools:

• GnuPG - for message encryption and signing;
• uact - for cross-platform Unix administration;
• (optional) xyz - for security configuration compliance checks.
• (optional) scw - the scheduled command wrapper, to centrally manage scheduled tasks.

To build and run the central management system, this library is required:

• Ulfius - HTTP framework for REST applications.

The libcurl, Jansson, and Ulfius libraries are available as packages on many major platforms (libcurl4-gnutls-dev, libjansson-dev, and libulfius-dev on Debian, for example). The uact, xyz, and scw tools have no dependencies of their own, so they are trivial to install.

Getting started

TODO

Suggested ways to use PUCA

Patch management

In pucamgr, create groups to arrange your endpoints appropriately for your patch management process. For example: development, test, pre-production, fault-tolerant production, critical production. You can then use the patching status view for each group, and the associated package update deployment tools, to deploy the updates to each group in turn according to your change or patch management process.

You could also use the metrics exported for each group to allow your monitoring systems to raise alerts if any group contains unpatched endpoints.

Phased rollouts like this work best if you can maintain local mirrors of your operating system updates, which you synchronise with upstream at the start of each patch cycle, and have all of your endpoints pointing to your local mirrors instead of to the public ones. That way, each group gets the same set of updates - it's not a moving target.

Deploying locally built software

Set up your internal CI/CD pipelines such that they deliver your software as operating system packages in a repository you can use with your normal patch management tools (apt, dnf, pacman, and so on) - and configure your endpoints to point to that repository. Your release management team can then oversee software deployment through pucamgr, once you set up delegated actions that they can run.

The parmo tool can be useful for packaging software and maintaining local repositories.

Reducing the attack surface by switching off SSH

To minimise the attack surface of your estate, you could stop the "sshd" service on systems with puca installed, and use the central manager to switch it on only when needed.

To ensure that it isn't left on by accident, you could then use your preferred deployment mechanism to add a custom xyz check which treats an active "sshd" service as a security policy compliance failure. Endpoints with the service enabled will then appear in pucamgr has having deviated from their security baseline.

Copyright, bug reporting, and acknowledgements

Copyright (C) 2026 Andrew Wood.

License GPLv3+: GNU GPL version 3 or later https://www.gnu.org/licenses/gpl-3.0.html.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License, version 3, in "docs/COPYING". If not, see https://www.gnu.org/licenses/gpl-3.0.html.

Please report bugs or request features via the issue tracker linked from the home page.

The puca home page is at:

https://ivarch.com/p/puca

The latest version can always be found here.