Configuration
Files and Services
Sensor Configuration Directory
The Sensor configuration directory is /etc/upwind.
Sensor Configuration File
| File | Configures |
|---|---|
agent.yaml | The Sensor and the Scanner. Refer to Configuring the Upwind Sensor. |
agent-hostconfig.yaml | The hostconfig service. Refer to Disabling Dynamic Values. |
Sensor Services
| Systemd Service | Description |
|---|---|
| upwind-agent-hostconfig.service | Host configuration service |
| upwind-agent-scanner.service | Scanner - Scans the host filesystem. Refer to Host Scanner |
| upwind-agent-scanner.timer | Timer for the Scanner (Default: Every hour, scans when the last scan is older than 24 hours) |
| upwind-agent-update.service | Auto-Update service, runs on a timer |
| upwind-agent-update.timer | Timer for auto update service (Default: Every hour) |
| upwind-agent.service | Upwind Sensor |
Environment Variables
Below is a list of all the environment variables read by the installation script. These variables allow you to specify essential configuration details, such as the Upwind API credentials, logging preferences, service limits, and more.
The following environment variables are deprecated. Please refer to the Configuring the Upwind Sensor for more details.
UPWIND_AGENT_EXTRA_CONFIGUPWIND_SCANNER_EXCLUSIONSUPWIND_AGENT_LOG_LEVELUPWIND_AGENT_LOG_FORMAT
| Environment Variable | Description | Default |
|---|---|---|
UPWIND_CLIENT_ID | Upwind API Client ID (Required) | |
UPWIND_CLIENT_SECRET | Upwind API Client Secret (Required) | |
UPWIND_REGION | Upwind region. us, eu, me, or ap. | us |
UPWIND_TAGS | User-defined tags to pass to the backend. BYOC installations only. Refer to Configuring Tags. | unset |
UPWIND_AGENT_INSTALL_TYPE | Type of install: std (standard), bcc (older kernels), gvisor, or scanner-only | std |
UPWIND_AGENT_CLOUD_PROVIDER | Upwind Cloud Provider | unset |
UPWIND_AGENT_CLOUD_ACCOUNT_ID | Upwind Cloud Account ID | unset |
UPWIND_AGENT_ZONE | Upwind Cloud Account Zone | unset |
UPWIND_AGENT_VERSION | Upwind Agent Version | stable |
UPWIND_AGENT_INSTALL_ONLY | Don't start the Upwind Agent Service on completion | |
UPWIND_AGENT_NO_UPDATES | Do not enable and start the Upwind Agent Update Service/Timer | |
UPWIND_AGENT_CPUQUOTA | Set the Upwind Agent Service CPUQuota | 50% |
UPWIND_AGENT_MEMORYHIGH | Set the Upwind Agent Service MemoryHigh | 800M |
UPWIND_AGENT_MEMORYMAX | Set the Upwind Agent Service MemoryMax | 1024M |
UPWIND_HOSTCONFIG_VERSION | Set the Upwind Agent Host Config Helper Version | stable |
UPWIND_HOSTCONFIG_ENABLED | Enable the Upwind Agent Host Config Helper Service | true |
UPWIND_HOSTCONFIG_LOG_LEVEL | Set the log level in config for Host Config | info |
UPWIND_HOSTCONFIG_LOG_FORMAT | Set the log format in config for Host Config | logfmt |
UPWIND_HOSTCONFIG_EXTRA_CONFIG | Set extra config for the Upwind Agent Host Config Helper | |
UPWIND_SENSOR_ENABLED | Enable the Upwind Sensor Service | true |
UPWIND_SCANNER_ENABLED | Enable periodic scanning | true |
UPWIND_SCANNER_CPUQUOTA | Set the Upwind Agent Scanner Service CPUQuota | 50% |
UPWIND_SCANNER_CPUWEIGHT | Set the Upwind Agent Scanner Service CPUWeight | 25 |
UPWIND_SCANNER_IOWEIGHT | Set the Upwind Agent Scanner Service IOWeight | 25 |
UPWIND_SCANNER_MEMORYHIGH | Set the Upwind Agent Scanner Service MemoryHigh | calculated based on host memory |
UPWIND_SCANNER_MEMORYMAX | Set the Upwind Agent Scanner Service MemoryMax | calculated based on host memory |
UPWIND_SCANNER_MIN_HOST_MEM | Minimum host memory (in kB) required to enable the Upwind Agent Scanner Service | 7000000 |
UPWIND_PACKAGE_MANAGER | Set to apt-get, dnf, or yum to force selection of a package manager (autodetects package manager if unset) | unset |
UPWIND_AGENT_* resource limits apply only to the Sensor service. To limit the Scanner, use the UPWIND_SCANNER_* variables. Refer to Resource Limits.
These variables can be set to configure various aspects of the Upwind Agent according to your specific requirements. If
the sensor will not be able to detect the cloud provider via IMDS, the UPWIND_AGENT_CLOUD_PROVIDER and UPWIND_AGENT_CLOUD_ACCOUNT_ID variables
must be set.
Configuring Tags
The UPWIND_TAGS variable applies only to Bring Your Own Cloud (BYOC) installations.
Set the tags as a comma-separated list of key:value pairs, with no spaces:
export UPWIND_TAGS="host:taas4m186,kind:triage,env:public"
Configuring the Upwind Sensor
To configure the Upwind Sensor according to your environment and security requirements, you can update the /etc/upwind/agent.yaml
to provide additional configuration of the sensor and scanner. Default configuration values are described below.
| Flag | Description | Default |
|---|---|---|
| platform | Installation platform. "host" configures the agent with default behavior suitable for running on a host as opposed to in Kubernetes or ECS cluster. The default is "auto" which determines platform automatically. | "auto" |
| region | Target region for Upwind domains. "us", "eu", or "me" | "us" |
| log-format | Logging format | "logfmt" |
| log-level | Logging level | "info" |
| install-type | Installation type, to distinguish from Cloud Scanner | "std" |
| enable-scans | Whether upwind-agent-scanner.timer systemd unit should be enabled | true |
| update-timer | Interval that the Sensor Update Helper runs on | 24h |
| exclusions | Additional paths to exclude from scans, as a space-separated list of glob patterns in quotes, relative to the scan path. Example: exclusions: "./data/** ./var/cache/build/**" excludes /data and /var/cache/build. Refer to Adding Exclusions for the syntax rules. | unset |
| exclude-mount-types | Additional mount fstypes to exclude from path scans. The list must be a space separated list in quotes. | unset |
| disable-default-excludes | Turn off the default path exclusions | false |
| max-file-size-to-scan | Skip files larger than this size, in bytes | 1073741824 (1 GiB) |
Example agent.yaml:
region: "us"
platform: "host"
install-type: "std"
agent-version: "0.131.2"
auth-client-id: "xxxx"
auth-client-secret: "xxxx"
log-format: "logfmt"
log-level: "info"
update-timer: "28"
enable-scans: true
exclusions: "./etc/** ./var/lib/misc/**"
agent-version sets the desired Sensor version. When it is set to a specific version (as in the example above), the Sensor is pinned to that version: the auto-update service continues to run on its timer, but it will not upgrade the Sensor, effectively turning off automatic updates. To keep receiving automatic updates, set agent-version to stable (or leave it unset), which resolves to the latest stable release on each update cycle. To disable the auto-update service and timer entirely, set the UPWIND_AGENT_NO_UPDATES environment variable.
Setting Environment Variables
Before running the installation or configuration script for the Upwind Sensor, set the desired environment variables in your shell. Use the export command for each variable you wish to configure:
export VARIABLE_NAME="value"
Replace VARIABLE_NAME with the name of the variable you're setting, and "value" with the desired setting.
Installing the Upwind Sensor
After setting the environment variables, you can install the Upwind Sensor by executing the following command:
curl -s https://get.upwind.io/sensor.sh | bash -s install
This command downloads and runs the installation script with the environment variables you've set, ensuring the sensor is configured as per your specifications.
Editing Configuration After Installation
If you need to edit the configuration after installation, you can modify the environment variables and the flags and re-run the configuration part of the script as follows:
curl -s https://get.upwind.io/sensor.sh | bash -s configure
This command will re-apply the configuration changes based on the newly set environment variables.
By following these steps, you can ensure that your Upwind Sensor is customized to meet the specific needs of your infrastructure and security policies.
Proxy Configuration
The sensor and the scanner and hostconfig tool will respect the HTTP_PROXY family of environment variables. Set the HTTP_PROXY and HTTPS_PROXY to your proxy server's URL. The value of the NO_PROXY variable should be the IP addresses or domains that should not be proxied and depends on environment.
HTTP_PROXY / http_proxy
Used as the proxy URL for HTTP requests unless overridden by NO_PROXY.
HTTPS_PROXY / https_proxy
Used as the proxy URL for HTTPS requests unless overridden by NO_PROXY.
NO_PROXY / no_proxy
Specifies a string that contains comma-separated values specifying hosts that should be excluded from proxying. Each value is represent by:
- an IP address (
1.2.3.4) - an IP address prefix in CIDR notation (
1.2.3.0/24) - a domain name
An IP address prefix and domain name can also include a literal port
number (
1.2.3.4:80). A domain name matches that name and all subdomains.
Most commonly these values are configured globally for the host, but can be configured
for the upwind components by adding the proxy settings to the /etc/upwind/agent.env file.
For example:
HTTP_PROXY=http://proxy.example.com:port
HTTPS_PROXY=http://proxy.example.com:port
NO_PROXY=localhost,127.0.0.1,.example.com
Logging to a File
By default the Upwind Sensor logs to stdout/stderr, which systemd forwards to the journal. To write logs to a file instead, add a systemd drop-in override for the sensor service. Do not edit the unit file itself, the installer regenerates it on upgrade. Drop-ins are preserved.
sudo mkdir -p /etc/systemd/system/upwind-agent.service.d
sudo tee /etc/systemd/system/upwind-agent.service.d/logging.conf <<'EOF'
[Service]
StandardOutput=append:/var/log/upwind-agent.log
StandardError=inherit
EOF
sudo systemctl daemon-reload
sudo systemctl restart upwind-agent.service
The same override can be applied to upwind-agent-scanner.service and upwind-agent-hostconfig.service.
append:requires systemd 240 or newer. On older versions (for example RHEL 8) usefile:instead, which truncates the file on every service restart.- systemd keeps the file open, so rotate it with
logrotateusing thecopytruncateoption. - The drop-in is not removed by
sensor.sh uninstall. Delete the directory manually if needed.
Disabling Dynamic Values
By default, the hostconfig tool retrieves configuration values dynamically from
the Upwind backend, in the same way the Upwind operator does on Kubernetes. It
writes these values to /etc/upwind/agent.yaml, and they take precedence over
local edits. If a setting you changed locally, such as exclusions or
enable-scans, reverts on its own, a value from the backend is overwriting it.
To pin the tool to its local configuration instead, set dynamic-values-enabled to
false in /etc/upwind/agent-hostconfig.yaml:
dynamic-values-enabled: false
Restart the service to apply the change:
sudo systemctl restart upwind-agent-hostconfig.service
With dynamic values disabled, the host no longer picks up configuration changes from Upwind, and agent.yaml becomes the only source of configuration. Manage it with your configuration management tool so hosts don't drift apart.
Prerequisite:
- Hostconfig version >=
0.11.1
Function In-Use
In-use detection identifies which functions your workloads actually execute at runtime, so vulnerabilities can be prioritized by real exposure rather than by presence alone. Refer to Function In-Use for how the feature works.
In-use monitoring as a whole is controlled by inuse-events, which is enabled
by default. Each runtime is then enabled individually in /etc/upwind/agent.yaml.
| Flag | Description | Default |
|---|---|---|
| inuse-events | Monitor in-use events. Acts as the master switch for all runtimes below. | true |
| inuse-bash | Enable Bash hooks | false |
| inuse-golang | Enable Golang in-use events | false |
| inuse-java | Enable Java in-use events | false |
| inuse-nodejs | Enable Node.js in-use events | false |
| inuse-php | Enable PHP in-use events | false |
| inuse-python | Enable Python in-use events | true |
| inuse-native | Enable native hunt functions for compiled binaries | true |
Example agent.yaml enabling every supported runtime:
inuse-events: true
inuse-bash: true
inuse-golang: true
inuse-java: true
inuse-nodejs: true
inuse-php: true
inuse-python: true
inuse-native: true
Restart the sensor to apply the change:
sudo systemctl restart upwind-agent.service
Related Pages
- Host Scanner - how the Scanner works, resource limits, default exclusions, and how to add your own.
- Golden Images - bake the Sensor into an image such as an AMI.
- Private IP Ranges - add your own ranges to the ones the Sensor treats as private network traffic.