AlertSamurai Agent

Host monitoring agent for AlertSamurai platform. Collects system metrics (CPU, RAM, disk, network) and sends them to the AlertSamurai API.

AlertSamurai is a distributed uptime monitoring service that allows you to monitor your websites and APIs from multiple geographic locations. The service is managed through a Telegram bot @AlertSamuraiBot.

Features

• ✅ Host metrics collection (CPU, RAM, disk, network)
• ✅ Automatic registration with AlertSamurai API
• ✅ Heartbeat mechanism for health monitoring
• ✅ Periodic metrics reporting
• ✅ Region and country detection
• ✅ Network discovery - automatic detection of active TCP/UDP connections to external services

Installation

npm install -g @alertsamurai/agent
# or
yarn global add @alertsamurai/agent

Usage

Using API key

npx @alertsamurai/agent --api-key <your-api-key>

With custom API URL

npx @alertsamurai/agent --api-key <your-api-key> --api-url https://api.alertsamurai.com

Using environment variables

AGENT_API_KEY=<your-api-key> AGENT_API_URL=https://api.alertsamurai.com npx @alertsamurai/agent

With custom log level

LOG_LEVEL=debug AGENT_API_KEY=<your-api-key> npx @alertsamurai/agent

Configuration

Environment Variables

• AGENT_API_KEY - User API key (required, one per account)
• AGENT_API_URL - API URL (optional, defaults to http://localhost:3000)
• AGENT_NAME or AGENT_ID - Agent name/ID (optional, defaults to hostname)
• AGENT_HOSTNAME - Hostname to use (optional, defaults to system hostname). Useful in Docker to override container hostname.
• AGENT_METRICS_INTERVAL - Metrics collection interval in milliseconds (default: 60000 = 60 seconds)
• AGENT_DISCOVERY_ENABLED - Enable network discovery (default: false, set to "true" to enable)
• AGENT_DISCOVERY_INTERVAL - Network discovery interval in milliseconds (default: 300000 = 5 minutes)
• AGENT_USER_AGENT - Custom user agent string (optional, defaults to "AlertSamuraiAgent/1.0")
• EXTERNAL_IP_SERVICE_URL - URL for external IP detection service (optional, defaults to "https://api.ipify.org?format=json")
• LOG_LEVEL - Logging level (optional, defaults to "log"). Supported values: verbose, debug, log, warn, error. When set, includes all levels from the specified level and above.
• NODE_ENV - Node.js environment (optional, defaults to "development")

Note: Metrics aggregation settings (aggregation interval, collection frequency, aggregation type) are configured via the API and retrieved automatically during agent registration.

API Key

The API key is unique per user account and is used for authentication with the AlertSamurai API. The user ID is automatically determined by the API based on the provided API key.

Get your API key from the AlertSamurai Telegram bot @AlertSamuraiBot using the /agent command.

Network Discovery

The agent automatically discovers active network connections by monitoring /proc/net/tcp and /proc/net/udp on Linux systems. This allows you to:

• See which external services your host is connecting to
• Monitor active TCP/UDP connections
• Build a service map showing network topology
• Track connection patterns and identify dependencies

How It Works

Network discovery works by reading Linux kernel network connection tables:

1. TCP Connections: Reads /proc/net/tcp to get active TCP connections
2. UDP Connections: Reads /proc/net/udp to get active UDP connections
3. Address Parsing: Converts hex-encoded IP addresses and ports to readable format
4. Hostname Resolution: Performs reverse DNS lookup for remote IP addresses
5. Connection Filtering: Filters out LISTEN sockets and localhost connections to focus on external services

The agent collects connection data periodically (default: every 5 minutes) and sends it to the AlertSamurai API for visualization.

Discovery Data

Discovery data includes:

• Remote IP addresses and ports
• Resolved hostnames (via reverse DNS)
• Connection protocols (TCP/UDP)
• Connection states
• Process information (when available)

Platform Support

⚠️ Important: Network discovery is Linux-only and requires:

• Access to /proc/net/tcp and /proc/net/udp files
• Linux kernel with /proc filesystem support
• Proper permissions to read network connection tables

On non-Linux systems (macOS, Windows), discovery will be automatically disabled. The agent will continue to work normally for metrics collection, but network discovery features will not be available.

Docker Considerations

When running in Docker, you need to use --pid=host flag to give the container access to the host's /proc/net files:

docker run --pid=host ...

Without this flag, the agent won't be able to read network connection information.

Docker Deployment

For network discovery to work properly, the agent needs access to /proc/net:

docker run \
  --restart=unless-stopped \
  --name alertsamurai-agent \
  --pid=host \
  -e AGENT_API_KEY=<your-api-key> \
  -e AGENT_API_URL=https://api.alertsamurai.com \
  -e AGENT_HOSTNAME=$(hostname) \
  -e AGENT_DISCOVERY_ENABLED=true \
  -e LOG_LEVEL=log \
  bearlogin/alertsamurai-agent:latest

Important flags:

• --pid=host - Required for network discovery (access to /proc/net/tcp and /proc/net/udp)
• --network=host - Optional, but recommended for better network visibility

Metrics Collected

• CPU: Usage percentage, load average, number of cores
• Memory: Total, free, used memory and usage percentage
• Disk: Total, free, used disk space and usage percentage (per filesystem)
• Network: Bytes received/sent per network interface
• Network Discovery: Active TCP/UDP connections to external services
• System: Uptime, hostname, platform, architecture

Development

# Install dependencies
yarn install

# Development mode
yarn dev

# Build
yarn build

# Run production build
yarn start:prod

Learn More

• Telegram Bot: @AlertSamuraiBot
• Start monitoring: Open @AlertSamuraiBot in Telegram and use /start command

License

MIT