On-Premises Deployment

Overview

The AlphaSOC Analytics Engine (AE) processes telemetry and generates security findings in your environment. It parses and normalizes incoming logs, enriches indicators using AlphaSOC Cloud, and applies detections locally. Findings can be retrieved through the local API or delivered to a configured destination.

AE is distributed through the Snap Store. Snap manages the engine and its optional configuration UI as services and delivers package updates. For deployment requirements that cannot use Snap, contact support@alphasoc.com.

Cloud connectivity and data handling

An on-premises deployment requires connectivity to AlphaSOC Cloud for authentication, license validation, and indicator enrichment. Plan for an internet-connected deployment.

Primary telemetry processing and pipeline storage are local. The engine sends the following information to AlphaSOC Cloud:

Purpose	Information sent
Authentication and licensing	Requests to validate credentials and license status.
Indicator enrichment	DNS names and query types; destination IP addresses, ports, and protocols; HTTP URLs and user agents; remote TLS certificate hashes and JA3 hashes; and remote IP addresses and user agents from audit events. Each indicator summary includes the matching event count and the number of associated endpoints.
Operational metrics	Queue activity and backlogs, parsing and detection counts, storage usage and latency, and process health such as CPU and memory usage.
Engine log uploads	Engine diagnostic logs at or above the configured upload level. These are engine logs, rather than a separate upload of all ingested telemetry. See Log uploads.

Configuring a findings destination also sends findings to that destination.

Prerequisites

• A modern Linux distribution with snapd installed.
• Administrative access to install the package and manage its configuration.
• An AlphaSOC API key, generated in the AlphaSOC Console.
• Persistent disk storage for queues, processing state, and findings.
• Network access appropriate to your chosen ingestion and delivery methods.

Sizing

Use 1 CPU core and 2 GB of RAM per 5,000 events per second as a starting point for capacity planning. This is a rule of thumb, not a throughput guarantee. For example, start with 4 CPU cores and 8 GB of RAM for 20,000 events per second, then measure performance with your telemetry and detection set.

CPU requirements depend on the number and complexity of loaded rules, especially Sigma rules. Parsing, correlations, and anomaly detection also affect resource usage.

Provide storage capable of at least a few thousand IOPS for persistent processing state and temporary backlogs. Additional RAM allows the operating system to cache frequently accessed data and reduce disk I/O, so leave memory available for the filesystem cache beyond the engine's expected usage. Monitor IOPS, I/O latency, free disk space, and queue growth under representative load to determine whether storage is becoming a bottleneck.

Network access

Connection	Requirement
AE to AlphaSOC Cloud	Outbound HTTPS on TCP 443 to api.alphasoc.net for authentication, enrichment, metrics, and configured log uploads.
Host to Snap Store	Connectivity for package installation and updates.
Telemetry clients and findings consumers to AE	Access to the configured API listener.
S3-compatible upload clients to AE	Access to the S3 listener, if enabled.
Administrators to the optional UI	SSH forwarding, or controlled access to TCP 3001 for HTTP and TCP 3002 for HTTPS.
AE to telemetry sources and findings destinations	Access to the external services selected for ingestion and delivery.

Allow access to the listeners required by your integration. The API listener and S3 listener use separately configured ports.

Installation

Install the package from the Snap Store:

sudo snap install alphasoc-ae

Inspect the installed services:

snap services alphasoc-ae

The package includes the alphasoc-ae.ae engine service and the alphasoc-ae.ui configuration UI. The engine needs an API key before it can start successfully. Continue with configuration before connecting clients.

Configuration

You can configure AE directly through YAML files. The web UI is optional.

Configuration files and precedence

The Snap package uses this default configuration structure:

/var/snap/alphasoc-ae/current/etc/config/
|-- 00-default.yaml
`-- 10-ui/
    |-- 10-var.yaml
    |-- 20-user.yaml
    `-- 99-const.yaml

The UI creates 10-var.yaml and 20-user.yaml as needed. They may not be present until you save settings in the UI.

AE reads directory entries in filename order, recursively processing each subdirectory before continuing to the next entry. Later values override earlier values for the same setting. Lists are replaced rather than appended.

Choose one place to manage each setting:

• If you use the UI, enter custom YAML in its configuration editor. The UI stores it in 10-ui/20-user.yaml, where it remains visible and editable in the UI. Saving the editor replaces the contents of this file.
• If you manage configuration directly or with a configuration management tool, create a YAML file at the root of the configuration directory. A name such as 90-local.yaml makes it load after the entire 10-ui directory, so the UI cannot overwrite or take precedence over those settings. This is useful for settings enforced by the system administrator.

Avoid defining the same setting in both places. In the examples below, “update the configuration” means editing whichever file you chose.

Every file in the configuration tree is read, regardless of its extension. Keep backup copies, editor swap files, credentials, certificates, and Sigma rules outside this directory. A file named 90-local.yaml.bak is not ignored.

Relative configuration paths resolve from /var/snap/alphasoc-ae/current/. Keep configuration assets within the Snap data directories so the confined services can access them.

Apply changes

Restart all AE services after editing configuration files:

sudo snap restart alphasoc-ae

Confirm that the engine and UI services are active:

snap services alphasoc-ae

Review the latest service logs for errors:

sudo snap logs -n=100 alphasoc-ae

API key

The package configures api.keyfile to read /var/snap/alphasoc-ae/current/etc/alphasoc-key. Open that file and replace its contents with your AlphaSOC API key:

sudoedit /var/snap/alphasoc-ae/current/etc/alphasoc-key
sudo snap restart alphasoc-ae

API keys and ingestion tokens created in the AlphaSOC Console also work with the supported on-premises API endpoints. Use the credential type required by the endpoint. UI login credentials and embedded S3 server credentials are separate from these credentials.

API listener and TLS

Place your PEM certificate chain and private key in /var/snap/alphasoc-ae/current/etc/tls/, then update the configuration:

server:
  bind: ":443"
  tls:
    cert: etc/tls/ae-cert.pem
    key: etc/tls/ae-key.pem

Use a certificate valid for the hostname clients connect to, and restrict access to the private key. The API and optional UI use the same certificate and key. The S3 listener can use the same pair or a separate pair.

Without an explicit server.bind, the API defaults to port 80 without TLS or port 443 when a certificate is configured. An address such as :443 listens on all interfaces; specify an IP address, such as 192.0.2.10:443, to select a particular interface.

S3-compatible ingestion listener

Enable this listener if clients will upload log files using the S3 protocol. Update the configuration with the following settings, adjusting the hostname, port, and certificate paths:

s3Server:
  bind: ":8443"
  tls:
    cert: etc/tls/ae-cert.pem
    key: etc/tls/ae-key.pem
  auth:
    hosts:
      - ae.example.com:8443
    keyFile: etc/s3-credentials

The client endpoint for this example is https://ae.example.com:8443. Configure the client to use the events bucket. AE accepts the region used by the client's signature. The hosts list must match the hostname and port used by clients to sign S3 requests; entries do not include https:// or a path.

On startup, AE creates the credential file if it does not exist. Its first line is the access key ID, and its second line is the secret access key. Retrieve these on the server after restarting AE:

sudo cat /var/snap/alphasoc-ae/current/etc/s3-credentials

Use these local credentials for this listener. The cloud S3 credential generation instructions in the transport guide do not apply to this local credential file.

For best compatibility, configure clients to send individual uploads of 10 MB or less and disable multipart uploads.

Log uploads

The engine supports uploading diagnostic logs to AlphaSOC Cloud. The default upload threshold is notice. To include informational messages, update the configuration with:

logs:
  uploadlevel: info

The supported values are * (all messages), debug, info, notice, warn (or warning), error, crit (or critical), and none. A level includes messages at that severity and above. Use none to disable log uploads.

logs:
  uploadlevel: none

This setting affects log uploads. Local logging and operational metric exports are separate.

Optional web UI

Create UI credentials interactively:

sudo /snap/bin/alphasoc-ae.ui-config

Forward the UI ports from your workstation:

ssh -L 3001:localhost:3001 -L 3002:localhost:3002 <user>@<server>

Open http://localhost:3001. HTTPS is available on port 3002 after configuring TLS; use a hostname matching the certificate when accessing it.

The UI provides configuration and monitoring controls. Apply Changes saves settings and restarts the engine. Remember that a later configuration file can override UI settings. Run alphasoc-ae.ui-config again to change the UI login credentials.

Send telemetry and retrieve findings

AE can receive telemetry through the local HTTPS API or S3-compatible listener, and can pull files from Amazon S3 and Google Cloud Storage. See Collecting Data for supported formats and transports. The individual transport guides describe the data source and authentication requirements; use your local AE endpoint where applicable.

Common deployments use Cribl to send telemetry to the local S3 listener, or AlphaSOC for Splunk to retrieve findings from the local API. Contact support for the on-premises YAML required for pull-based Amazon S3 or Google Cloud Storage collection.

For local findings retrieval, use GET /v1/findings on the configured API listener. Consult the API reference for authentication and pagination. See Escalating Findings for supported formats and push destinations.

By default, findings are stored locally for API retrieval when no push outputs are configured. Configuring a push output disables local findings retention by default. Decide whether consumers will pull findings or receive pushed findings before enabling an output. Contact support if you need both modes.

Operations and storage

Service management

# Check whether the AE services are active.
snap services alphasoc-ae

# View recent logs from the AE services.
sudo snap logs -n=100 alphasoc-ae

# Follow logs from the engine service.
sudo snap logs -f alphasoc-ae.ae

# Restart all AE services after a configuration change.
sudo snap restart alphasoc-ae

# Stop or start all AE services.
sudo snap stop alphasoc-ae
sudo snap start alphasoc-ae

# Inspect the installed version and tracked channel.
snap list alphasoc-ae
snap info alphasoc-ae

Snap runs the engine as snap.alphasoc-ae.ae and the UI as snap.alphasoc-ae.ui. You can also inspect these systemd services directly:

sudo systemctl status snap.alphasoc-ae.ae
sudo systemctl status snap.alphasoc-ae.ui
sudo journalctl -u snap.alphasoc-ae.ae -f

Updates

Snap updates the package automatically. To update it immediately from the currently tracked channel, run:

sudo snap refresh alphasoc-ae

Automatic refresh times can be adjusted using Snap's update management options.

File locations

Path	Contents
/var/snap/alphasoc-ae/current/etc/config/	Layered YAML configuration.
/var/snap/alphasoc-ae/current/etc/	API key, certificates, and other configuration assets.
/var/snap/alphasoc-ae/current/ui.dat	UI credential store.
/var/snap/alphasoc-ae/common/ae.db/	Persistent runtime data, including queues, stored payloads, detection state, and findings state. Despite the name, this is a directory.
/var/snap/alphasoc-ae/common/ae-process-logs/	Local engine process logs in package versions that include file logging.

current points to the active Snap revision's data directory. Its contents are carried forward during an update. Persistent runtime data lives under common, which is shared across revisions and avoids copying the runtime database on each update.

Do not copy /var/snap/alphasoc-ae/common/ae.db/ while AE is running. Active writes can produce an inconsistent or malformed copy. Stop the AE services before copying the data directory.