Quick Start Guide

This guide will help you get SafeNetworking up and running quickly. You’ll configure the basic components, set up your AutoFocus API key, and verify that the system is processing events.

If you received a pre-installed VM from your Palo Alto Networks account team, it comes ready to go and you can skip most of these steps. You’ll only need to configure your AutoFocus API key and firewall syslog settings.

Prerequisites

Before you begin, ensure you have:

System Requirements

Ubuntu 18.04 LTS or compatible Linux distribution
Minimum 8GB RAM (16GB recommended)
Python 3.6 or higher
Root or sudo access

Required Accounts

Palo Alto Networks AutoFocus subscription
AutoFocus API key (obtainable from the AutoFocus portal)

Network Access

Firewall can send syslog to SafeNetworking system on UDP port 5514
SafeNetworking system can reach autofocus.paloaltonetworks.com (HTTPS)

Installation

1. Clone the Repository

cd ~
git clone https://github.com/PaloAltoNetworks/safe-networking.git
cd safe-networking

2. Run the Setup Script

The setup.sh script automates the installation of ElasticStack components and SafeNetworking configuration.

sudo ./install/setup.sh

This script will:

Create necessary directories (~/es_backup for Elasticsearch backups)
Set up Python virtual environment in .env/
Install Python dependencies from requirements.txt
Configure Elasticsearch, Logstash, and Kibana
Set system limits for Elasticsearch
Install index mappings and templates
Enable services to start on boot

The setup script will modify system configuration files in /etc/elasticsearch/, /etc/logstash/, and /etc/kibana/. Backups are created automatically with timestamps.

3. Configure AutoFocus API Key

Edit the .panrc configuration file in your home directory:

nano ~/.panrc

Add your AutoFocus API key:

# API Key for Autofocus
AUTOFOCUS_API_KEY = "your-api-key-here"

You can obtain your AutoFocus API key by logging into the AutoFocus portal and navigating to Settings → API Key.

4. Verify ElasticStack Services

Check that all services are running:

# Check Elasticsearch
curl http://localhost:9200

# Check Logstash is listening
netstat -tuln | grep 5514

# Check Kibana
curl http://localhost:5601

Expected responses:

Elasticsearch: JSON response with cluster information
Logstash: UDP port 5514 should be listening
Kibana: HTTP 200 response or redirect

Configure Your Firewall

Configure your Palo Alto Networks firewall to send syslog events to SafeNetworking.

Syslog Server Configuration

Add Syslog Server Profile

Navigate to Device → Server Profiles → Syslog and create a new profile:

Name: SafeNetworking
Server: IP address of your SafeNetworking system
Port: 5514
Facility: LOG_USER
Format: Default

Configure Log Forwarding

Navigate to Objects → Log Forwarding and create profiles for:

Threat Logs: Forward DNS threat logs to SafeNetworking syslog profile
Traffic Logs: (Optional) Forward traffic logs for additional context

Apply to Security Policies

Edit your security policies to use the log forwarding profile.

Example Syslog Configuration

<entry name="SafeNetworking">
  <server>
    <entry name="SafeNetworking-Server">
      <server>192.168.1.100</server>
      <transport>UDP</transport>
      <port>5514</port>
      <format>Default</format>
      <facility>LOG_USER</facility>
    </entry>
  </server>
</entry>

Start SafeNetworking

Now you’re ready to start the SafeNetworking application.

Start the Application

cd ~/safe-networking
./sfn start

You should see output similar to:

[INFO]    : 2019-06-15 10:30:15 : sfn:start:[46]:140234567890 : INIT - SafeNetworking application initializing with loglevel of DEBUG
[INFO]    : 2019-06-15 10:30:15 : sfn:start:[48]:140234567890 : ElasticSearch host is: localhost:9200
[INFO]    : 2019-06-15 10:30:15 : sfn:initBackgroundProcs:[192]:140234567890 : INIT - Starting with total proc count of 16
[INFO]    : 2019-06-15 10:30:17 : sfn:initProcs:[200]:140234567891 : INIT - SafeNetworking server started @ localhost:5000
[INFO]    : 2019-06-15 10:30:17 : sfn:start:[46]:140234567890 : INIT - Background processes initialized

The application will continue running in the foreground. To run it in the background, use nohup ./sfn start & or set up a systemd service.

Verify Processing

Check the SafeNetworking log file:

tail -f ~/safe-networking/log/sfn.log

You should see log entries indicating:

Background processes initialized
DNS processing routines started
AutoFocus point totals being queried
Events being processed (once firewall logs arrive)

Access Kibana Dashboards

Once SafeNetworking is running and processing events, you can view the data in Kibana.

Import Visualizations

Access Kibana

Open your browser and navigate to: http://<your-server-ip>:5601

Create Index Patterns

Go to Management → Index Patterns and create patterns for:

threat-*
sfn-domain-details*
sfn-tag-details*
sfn-iot-details* (if using IoT features)

Use @timestamp as the time field.

Import Dashboards

Navigate to Management → Saved Objects → Import and import:

~/safe-networking/install/kibana/export.json

Select the appropriate index patterns when prompted.

Available Dashboards

After importing, you’ll have access to several pre-built dashboards:

Safe Networking Overview: High-level threat summary
DNS Threat Analysis: Detailed DNS threat events and malware families
IoT Threat Detection: IoT-specific threat intelligence
GTP/SCTP Events: Mobile network event analysis
Malware Timeline: Temporal analysis of malware detections

Verify Event Enrichment

To verify that SafeNetworking is enriching events with AutoFocus data:

Generate DNS Traffic

Generate some DNS queries on your network that will be logged by the firewall.

Check Elasticsearch

Query Elasticsearch for recent threat events:

curl -X GET "localhost:9200/threat-*/_search?pretty" -H 'Content-Type: application/json' -d'
{
  "query": {
    "match": {
      "ThreatCategory": "dns"
    }
  },
  "size": 5,
  "sort": [{"@timestamp": "desc"}]
}'

Verify Enrichment

Look for enriched fields in the response such as:

malware_family
tag_groups
confidence_level
Domain reputation data

CLI Commands

SafeNetworking provides several CLI commands for management:

# Start SafeNetworking
./sfn start

# Check version
./sfn version

# Admin functions (export data)
./sfn admin --datadump --index threat-* --sortfield @timestamp --outfile output.txt

# IoT data dump
./sfn iot --datadump

# Load CSV data into Elasticsearch
./sfn load <csvfile> <index-name>

Troubleshooting

SafeNetworking won't start - API key error

If you see: CRITICAL - API Key for Autofocus is not set in .panrc, exitingSolution: Edit ~/.panrc and set your AUTOFOCUS_API_KEY

No events appearing in Elasticsearch

Check:

Firewall syslog configuration is correct
Logstash is listening: netstat -tuln | grep 5514
No firewall rules blocking UDP 5514
Check Logstash logs: /var/log/logstash/logstash-plain.log

Elasticsearch connection errors

Check:

Elasticsearch is running: curl localhost:9200
Check Elasticsearch logs: /var/log/elasticsearch/
Verify disk space and memory available

High AutoFocus API point usage

SafeNetworking caches domain information to reduce API calls. You can adjust caching behavior in .panrc:

# Cache domain info for 30 days (default)
DNS_DOMAIN_INFO_MAX_AGE = 30

# Reduce concurrent processes
DNS_POOL_COUNT = 8  # Default is 16

Next Steps

Full Installation Guide

Learn about advanced configuration options and production deployment best practices.

Configuration Reference

Detailed reference for all configuration parameters in .panrc.

For production deployments, consider setting up SafeNetworking as a systemd service and configuring log rotation for the SafeNetworking application logs.

Get Started

Core Concepts

Event Processing

Configuration

Operations

Quick Start

Quick Start Guide

Prerequisites

Installation

1. Clone the Repository

2. Run the Setup Script

3. Configure AutoFocus API Key

4. Verify ElasticStack Services

Configure Your Firewall

Syslog Server Configuration

Example Syslog Configuration

Start SafeNetworking

Start the Application

Verify Processing

Access Kibana Dashboards

Import Visualizations

Available Dashboards

Verify Event Enrichment

CLI Commands

Troubleshooting

Next Steps

Full Installation Guide

Configuration Reference

Build docs developers (and LLMs) love

Get Started

Core Concepts

Event Processing

Configuration

Operations

​Quick Start Guide

​Prerequisites

​Installation

​1. Clone the Repository

​2. Run the Setup Script

​3. Configure AutoFocus API Key

​4. Verify ElasticStack Services

​Configure Your Firewall

​Syslog Server Configuration

​Example Syslog Configuration

​Start SafeNetworking

​Start the Application

​Verify Processing

​Access Kibana Dashboards

​Import Visualizations

​Available Dashboards

​Verify Event Enrichment

​CLI Commands

​Troubleshooting

​Next Steps

Full Installation Guide

Configuration Reference

Build docs developers (and LLMs) love

Quick Start Guide

Prerequisites

Installation

1. Clone the Repository

2. Run the Setup Script

3. Configure AutoFocus API Key

4. Verify ElasticStack Services

Configure Your Firewall

Syslog Server Configuration

Example Syslog Configuration

Start SafeNetworking

Start the Application

Verify Processing

Access Kibana Dashboards

Import Visualizations

Available Dashboards

Verify Event Enrichment

CLI Commands

Troubleshooting

Next Steps