¶ (c) TechnoCore - All Rights Reserved.
NOTICE: All information contained herein is, and remains
the property of TechnoCore Automate.
The intellectual and technical concepts contained
herein are proprietary to TechnoCore Automate and
dissemination of this information or reproduction of this material
is strictly forbidden unless prior written permission is obtained
from TechnoCore Automate.
¶ ObjEnvironment.py
¶ Overview
Secure host-environment operations helper for the Axion framework. This module
provides a strictly allowlisted interface for executing system and process
management commands on the host. It is designed for both local maintenance
usage and authenticated API access, ensuring that only a predefined set of
safe operations can be performed.
The module does not inherit from ObjData and has no database dependency.
It inherits from Objects and operates as a standalone utility.
¶ Security Model
ObjEnvironment enforces multiple layers of protection to prevent misuse:
- Action allowlist: Only predefined actions are available. No
free-form shell command input is accepted. - Binary allowlist: Subprocess execution is restricted to known management
binaries:supervisorctl,docker,systemctl,kubectl,crontab,
journalctl, andgit. - No shell injection: All subprocess calls use
shell=Falsewith a
minimal, hardcodedPATHenvironment. - Token authentication: API access requires a valid token checked via
constant-timehmac.compare_digest. Tokens are sourced fromconfig.yaml
and/orAXION_ENVIRONMENT_*environment variables. - ACL validation: Optional ACL check via the platform's
Aclsubsystem
(report key:mgmt_environment_ops). - Input clamping: All user-supplied numeric parameters (timeouts, line
counts, limits) are clamped to safe ranges. - Output limits: Subprocess output is truncated at 120,000 characters.
- Service allowlist: Supervisor, Docker, K3s, and system-service control
actions validate target names before execution. System services are limited
to common web/cache daemons by default (apache2,httpd,caddy,
redis,redis-server) plus configured additions. - Path confinement: Backup directories and repository paths are validated
to stay within expected boundaries.
¶ ObjEnvironment Class
Inherits from: Objects (standalone, no ObjData)
¶ Class Constants
| Constant | Value | Description |
|---|---|---|
MAX_TIMEOUT_SECONDS |
60 | Hard ceiling for subprocess timeout |
DEFAULT_TIMEOUT_SECONDS |
20 | Default subprocess timeout |
MAX_OUTPUT_CHARS |
120,000 | Truncation limit for command output |
MAX_LINES |
500 | Maximum lines for log retrieval |
MAX_BACKUP_MB |
4,096 | Maximum backup archive size |
ALLOWED_BINARIES |
supervisorctl, docker, systemctl, kubectl, crontab, journalctl, git | Only these executables may run |
DEFAULT_SYSTEM_SERVICES |
apache2, httpd, caddy, redis, redis-server | Built-in allowlist for system daemon controls |
MUTATING_ACTIONS |
supervisor/docker/system-service start/stop/restart, k3s_scale/restart/apply, supervisor_reload, backup_create | Actions that modify state |
¶ Key Methods
| Method | Description |
|---|---|
execute_api(payload) |
Secure API entry point. Validates token + optional ACL, then dispatches the requested action. |
execute_local(action, params) |
Local trusted entry point. No token check. Intended for CLI and maintenance use. |
is_mutating_action(action) |
Class method. Returns True if the action modifies system state. |
¶ Registered Actions
| Action | Category | Description |
|---|---|---|
list_actions |
Meta | List all available actions with descriptions |
system_overview |
System | Read-only host overview (hostname, uptime, load, disk usage) |
supervisor_status |
Supervisor | Run supervisorctl status |
supervisor_start |
Supervisor | Start an allowlisted supervisor service |
supervisor_stop |
Supervisor | Stop an allowlisted supervisor service |
supervisor_restart |
Supervisor | Rolling restart for one or more selected allowlisted supervisor services. Stops one worker, waits for it to stop, starts it, verifies RUNNING, waits for stability, then moves to the next worker. |
supervisor_reload |
Supervisor | Run supervisorctl reread + update |
docker_list |
Docker | List Docker containers and current state |
docker_start |
Docker | Start a validated Docker container |
docker_stop |
Docker | Stop a validated Docker container |
docker_restart |
Docker | Restart a validated Docker container |
system_service_list |
System Services | Show status for allowlisted system services |
system_service_status |
System Services | Show status for one allowlisted system service |
system_service_start |
System Services | Start an allowlisted system service |
system_service_stop |
System Services | Stop an allowlisted system service |
system_service_restart |
System Services | Restart an allowlisted system service |
k3s_status |
K3s | Show K3s Kubernetes workload status via kubectl get |
k3s_scale |
K3s | Scale an allowlisted K3s workload |
k3s_restart |
K3s | Rollout restart an allowlisted K3s workload |
k3s_apply |
K3s | Apply an allowlisted manifest under the repository root |
cron_list |
Cron | List current user crontab entries |
cron_recent |
Cron | Read recent cron activity from journalctl or log files |
git_status |
Git | Run git status --short --branch (read-only) |
git_branch |
Git | Show current git branch |
git_log |
Git | Show recent commit log (read-only, configurable line count) |
git_remote |
Git | Show git remotes |
backup_create |
Backup | Create a .tar.gz code backup archive |
backup_list |
Backup | List available backup archives |
¶ Internal Methods
| Method | Description |
|---|---|
_dispatch(action, params, mode) |
Central dispatcher. Looks up action, calls handler, attaches timing metadata. |
_validate_api_access(payload) |
Token + ACL validation for API mode. |
_run_subprocess(command, params, cwd) |
Safe subprocess runner. Validates binary against allowlist, enforces timeout, uses shell=False. |
_run_supervisor_control(command, params) |
Validates service name against allowlist before delegating to _run_subprocess. |
_run_docker_control(command, params) |
Validates container name and configured Docker allowlist before delegating to _run_subprocess. |
_run_system_service_control(command, params) |
Validates system service name against the system-service allowlist before delegating to _run_subprocess. |
_validated_k3s_workload(params) |
Validates K3s namespace and workload name against configured allowlists. |
_validated_k3s_manifest(params) |
Confines K3s manifests to repository-relative allowlisted files. |
_read_cron_log_lines(lines) |
Fallback cron log reader. Scans /var/log/syslog, /var/log/cron, /var/log/messages. |
_repo_root() |
Resolves the repository root path from config or cwd. |
_backup_dir() |
Resolves and validates the backup directory path. |
_configured_tokens() |
Collects API tokens from environment variables and config.yaml. |
_token_allowed(provided, configured) |
Constant-time token comparison using hmac.compare_digest. |
_clamp_int(value, min, max, default) |
Safe integer parsing with range clamping. |
¶ Configuration
Settings are read from the environment section in config.yaml:
environment:
require_token: Y # Require API token for execute_api
require_acl: N # Require ACL validation
acl_report: mgmt_environment_ops # ACL report key
api_token: <token> # Single API token
api_tokens: <token1>,<token2> # Multiple API tokens
supervisor_services: svc1,svc2 # Allowlisted supervisor services
docker_containers: redis,web # Optional Docker container allowlist
docker_allow_all: Y # Permit valid container names when no allowlist is set
system_services: postgresql # Extra systemd services beyond built-in web/cache defaults
k3s_namespaces: default,apps # Optional K3s namespace allowlist
k3s_workloads: deployment/api # Optional K3s workload allowlist
k3s_manifests: k8s/api.yaml # Optional repo-relative manifest allowlist
repo_path: /path/to/repo # Override repository root
backup_root: /path/to/backups # Override backup root directory
backup_dir: /path/to/dir # Override backup subdirectory
backup_max_mb: 2048 # Maximum backup archive size in MB
Tokens can also be set via environment variables:
AXION_ENVIRONMENT_API_TOKEN- Single tokenAXION_ENVIRONMENT_API_TOKENS- Comma-separated tokensAXION_ENVIRONMENT_SUPERVISOR_SERVICES- Comma-separated service namesAXION_ENVIRONMENT_DOCKER_CONTAINERS- Comma-separated container namesAXION_ENVIRONMENT_SYSTEM_SERVICES- Comma-separated systemd service namesAXION_ENVIRONMENT_K3S_NAMESPACES- Comma-separated Kubernetes namespacesAXION_ENVIRONMENT_K3S_WORKLOADS- Comma-separated Kubernetes workload resourcesAXION_ENVIRONMENT_K3S_MANIFESTS- Comma-separated repo-relative manifest paths
¶ Command-Line Interface (CLI)
The module includes a CLI built with typer.
| Command | Description |
|---|---|
actions |
List all available actions as JSON |
local <action> [params_json] |
Execute a local trusted action (no token validation) |
api <payload_json> |
Execute an API-style payload (token validation enabled) |
python factory.core/ObjEnvironment.py actions
python factory.core/ObjEnvironment.py local system_overview
python factory.core/ObjEnvironment.py local git_status
python factory.core/ObjEnvironment.py local supervisor_status
python factory.core/ObjEnvironment.py local supervisor_restart '{"services":["report:report_00","report:report_01"],"stable_seconds":5}'
python factory.core/ObjEnvironment.py local docker_list
python factory.core/ObjEnvironment.py local docker_restart '{"container": "redis"}'
python factory.core/ObjEnvironment.py local system_service_restart '{"service": "caddy"}'
python factory.core/ObjEnvironment.py local k3s_status '{"namespace": "default"}'
python factory.core/ObjEnvironment.py local k3s_restart '{"namespace": "default", "resource": "deployment/api"}'
python factory.core/ObjEnvironment.py local k3s_scale '{"namespace": "default", "resource": "deployment/api", "replicas": 2}'
python factory.core/ObjEnvironment.py local k3s_apply '{"namespace": "default", "file": "k8s/api.yaml"}'
python factory.core/ObjEnvironment.py local git_log '{"lines": 10}'
python factory.core/ObjEnvironment.py local backup_create '{"label": "pre-deploy"}'
python factory.core/ObjEnvironment.py api '{"token": "abc123", "action": "system_overview"}'
¶ Response Format
All actions return a dictionary with consistent fields:
{
"ok": true,
"action": "system_overview",
"mode": "local",
"timestamp_utc": "2026-03-21T10:00:00Z",
"elapsed_ms": 42
}
On failure, ok is false and an error field contains the reason.