Example: Certificate Account Creation

1. Generate client certificate.

   pxGrid certificates are generated at Administration->pxGrid Services->Certificates. Here you should:

   • Generate a single certificate (without a certificate signing request).
   • Specify the username for the Common Name (CN).
   • Specify PKCS12 format.
   • Create the certificate.

   This exports a ZIP file containing a PKCS12 format file with the client public key certificate and private key:

   $ unzip 1544027591204_cert.zip
   Archive:  1544027591204_cert.zip
     inflating: paloalto04_.p12
   

2. Convert the PKCS12 format file to PEM.

   The PKCS12 key file is converted to PEM with no passphrase using the OpenSSL command line tool:

   $ openssl pkcs12 -in paloalto04_.p12 -out paloalto04-nopw.pem -nodes
   Enter Import Password:
   MAC verified OK
   
   $ ls -l paloalto04-nopw.pem
   -rw-r--r--  1 ksteves  ksteves  11301 Dec  5 09:47 paloalto04-nopw.pem
   

   Note

   The openssl -nodes argument means no DES.

   This certificate file can be used for the grid.py and gate.py --cert argument.

3. Activate account.

   Use the grid.py program to activate the account using the AccountActivate API request with the client certificate file:

   $ grid.py --verify ise-ca.pem --hostname ise-2.santan.local --activate -j --nodename paloalto04 --cert paloalto04-nopw.pem --desc 'test certificate account'
   account_activate: 200 OK None
   {
     "accountState": "PENDING",
     "version": "2.0.0.13"
   }
   

4. Approve account.

   The ISE administrator approves the account at Administration->pxGrid Services->All Clients.

   The approval can be verified by performing another activate request; the state should now be ENABLED:

   $ grid.py --verify ise-ca.pem --hostname ise-2.santan.local --activate -j --nodename paloalto04 --cert paloalto04-nopw.pem
   account_activate: 200 OK None
   {
     "accountState": "ENABLED",
     "version": "2.0.0.13"
   }
   

Example: Username/Password Account Creation

1. Create account.

   $ grid.py --verify ise-ca.pem --hostname ise-2.santan.local --create -j --nodename paloalto03
   account_create: 200 OK None
   {
     "nodeName": "paloalto03",
     "password": "jtKm2m3VNdd2xYiF",
     "userName": "paloalto03"
   }
   

2. Activate account.

   $ grid.py --verify ise-ca.pem --hostname ise-2.santan.local --activate -j --nodename paloalto03 --password jtKm2m3VNdd2xYiF --desc 'test account'
   account_activate: 200 OK None
   {
     "accountState": "PENDING",
     "version": "2.0.0.13"
   }
   

   You can now view the account with status Pending at Administration->pxGrid Services->All Clients.

3. Approve account.

   The ISE administrator approves the account at Administration->pxGrid Services->All Clients.

   The approval can be verified by performing another activate request; the state should now be ENABLED:

   $ grid.py --verify ise-ca.pem --hostname ise-2.santan.local --activate -j --nodename paloalto03 --password jtKm2m3VNdd2xYiF
   account_activate: 200 OK None
   {
     "accountState": "ENABLED",
     "version": "2.0.0.13"
   }
   

4. Get shared secret.

   Note

   The shared secret is only needed when using grid.py with username/password authentication; gate.py will automatically obtain the shared secrets using the provided password.

   The password is used to obtain a shared secret for a peer node. The peer nodename depends on the service name, which is com.cisco.ise.session for the session directory service, and com.cisco.ise.pubsub for the session pubsub service. A ServiceLookup API request is used to determine the peer node given the service name, followed by an AccessSecret API request to determine the shared secret:

   $ grid.py --verify ise-ca.pem --hostname ise-2.santan.local --lookup -j --nodename paloalto03 --password jtKm2m3VNdd2xYiF --name com.cisco.ise.session
   service_lookup: 200 OK None
   {
     "services": [
       {
         "name": "com.cisco.ise.session",
         "nodeName": "ise-mnt-ise-2",
         "properties": {
           "groupTopic": "/topic/com.cisco.ise.session.group",
           "restBaseURL": "https://ise-2.santan.local:8910/pxgrid/mnt/sd",
           "restBaseUrl": "https://ise-2.santan.local:8910/pxgrid/mnt/sd",
           "sessionTopic": "/topic/com.cisco.ise.session",
           "wsPubsubService": "com.cisco.ise.pubsub"
         }
       }
     ]
   }
   
   $ grid.py --verify ise-ca.pem --hostname ise-2.santan.local --lookup -j --nodename paloalto03 --password jtKm2m3VNdd2xYiF --name com.cisco.ise.pubsub
   service_lookup: 200 OK None
   {
     "services": [
       {
         "name": "com.cisco.ise.pubsub",
         "nodeName": "ise-pubsub-ise-2",
         "properties": {
           "wsUrl": "wss://ise-2.santan.local:8910/pxgrid/ise/pubsub"
         }
       }
     ]
   }
   
   $ grid.py --verify ise-ca.pem --hostname ise-2.santan.local --asecret -j --nodename paloalto03 --password jtKm2m3VNdd2xYiF --peernode ise-mnt-ise-2
   access_secret: 200 OK None
   {
     "secret": "4FhaXqreXpK1FeBW"
   }
   
   $ grid.py --verify ise-ca.pem --hostname ise-2.santan.local --asecret -j --nodename paloalto03 --password jtKm2m3VNdd2xYiF --peernode ise-pubsub-ise-2
   access_secret: 200 OK None
   {
     "secret": "Bx3HotDQuO7aZv36"
   }
   

   The secret can be verified by performing a getSessions API request:

   $ grid.py --verify ise-ca.pem --hostname ise-2.santan.local --nodename paloalto03 --sessions --baseurl 'https://ise-2.santan.local:8910/pxgrid/mnt/sd' --secret 4FhaXqreXpK1FeBW
   get_sessions: 200 OK None
   

   Note

   You can use the -j option to display the JSON response.

stdlib.localDB Miner

The class minemeld.ft.localdb.Miner implements a miner with a database containing indicators of various types (e.g., IPv4 and IPv6) and attributes for the indicators. The stdlib.localDB prototype is used to create the miner node.

gridmeld will populate the localDB node with IP indicators from pxGrid sessions using the MineMeld config API. The indicator sgt attribute will contain the SGT for each IP in the session.

dagPusherNg Output Node

The class minemeld.ft.dag_ng.DagPusher implements an output node which consumes indicators from an input node, in this case a localDB node, and uses the PAN-OS XML API to synchronize the indicators as registered-ip objects on configured firewalls and Panoramas. The dagPusherNg prototype is used to create the output node.

The prototype configuration specifies tag_attributes, which are the indicator attributes in localDB that will be used for the registered-ip object tags. The configuration can also specify a tag_prefix which is used to identify tags owned by the node; the default is mmld_. The tag name will be the concatenation of tag_prefix, tag_attribute and attribute; for example: mmld_sgt_Employees.

Dynamic Address Group objects (DAGs) can be created by using the object tags in a match expression. The DAGs can be used in a security policy as source and destination for policy enforcement.

dagPusher Implementations

There are two dagPusher implementations:

• class minemeld.ft.dag.DagPusher (prototype stdlib.dagPusher)

  This is the legacy node and should only be used if you are using Autofocus-hosted MineMeld, or when the devices are using PAN-OS 7.1.

• class minemeld.ft.dag_ng.DagPusher (prototype stdlib.dagPusherNg)

  This is the next generation node and is the recommended implementation to use. It contains a number of functional and performance enhancements made to the legacy node. It requires PAN-OS 8.0 or greater. dagPusherNg is available starting with MineMeld 0.9.62.

Nodes Configuration

We first need to create a local prototype from the pre-defined stdlib.dagPusherNg prototype so we can add the sgt attribute to the tag_attributes config.

A minemeldlocal.stdlib_dagPusherNg-sgt prototype is created at CONFIG->browse prototypes->Search "dagPusherNg"->select "stdlib.dagPusherNg". Then create a new local prototype from stdlib.dagPusherNg using NEW (create prototype from this) and add a config of { "tag_attributes": ["sgt"] }. This will result in the following prototype in /opt/minemeld/local/minemeldlocal.yml (we named the new prototype stdlib_dagPusherNg-sgt):

prototypes:
    stdlib_dagPusherNg-sgt:
        class: minemeld.ft.dag_ng.DagPusher
        config:
            tag_attributes:
            - sgt
        description: 'Push IP unicast indicators to PAN-OS 8.0 and greater devices
            via DAG.

            '
        development_status: EXPERIMENTAL
        indicator_types:
        - IPv4
        - IPv6
        node_type: output
        tags: []

Next we add a miner node using the stdlib.localDB prototype at CONFIG->browse prototypes->Search "localDB"->select "stdlib.localDB", then CLONE (new node from this prototype).

Then we add the output node at CONFIG->browse prototypes->Search "stdlib_dagPusherNg-sgt"->select "minemeldlocal.stdlib_dagPusherNg-sgt", then CLONE (new node from this prototype), and specify the localDB node created above as INPUT (this connects the output node to the input node).

Then COMMIT the configuration.

The nodes configuration, connecting the localDB miner to the dagPusherNg output node can be viewed in /opt/minemeld/local/config/running-config.yml:

nodes:
  localDB-1561848312020:
    inputs: []
    output: true
    prototype: stdlib.localDB
  stdlib_dagPusherNg-sgt-1561848485387:
    inputs:
    - localDB-1561848312020
    output: false
    prototype: minemeldlocal.stdlib_dagPusherNg-sgt

stdlib_dagPusherNg-sgt Node Configuration

The PAN-OS firewalls and Panoramas to be updated with registered-ip objects representing IP-SGT mappings are configured in the node's DEVICES tab. This updates a device list file containing YAML. The device list resides in the /opt/minemeld/local/config directory and is named node_device_list.yml, where node is the name of the output node:

$ cat /opt/minemeld/local/config/stdlib_dagPusherNg-sgt-1561848485387_device_list.yml
- {api_password: admin, api_username: admin, hostname: 192.168.1.102, name: vm-50-1}
- {api_password: admin, api_username: admin, hostname: 192.168.1.110, name: pa-220-2}

The device list file can also be created and updated manually. The device configuration variables are:

Variable Name	Type	Description	Default
hostname	string	PAN-OS hostname or IP address	null
api_username	string	user for type=keygen	null
api_password	string	password for type=keygen	null
api_key	string	key for API requests	null
name	string	optional friendly hostname	null

{
    "indicator_types": ["IPv4", "IPv6"],
    "include_networks": [],
    "exclude_networks": [],
    "attribute_map": {
        "ctsSecurityGroup": "sgt",
        "userName": "user"
    }
}

Session Policy Examples

The following JSON object will update the default policy to include the endpointOperatingSystem field using the localDB os attribute when it exists in a session.

$ cat policy1.json
{
    "attribute_map": {
        "ctsSecurityGroup": "sgt",
        "userName": "user",
        "endpointOperatingSystem": "os"
    }
}

The following JSON object will update the default policy to process only IPv4 indicator types.

$ cat policy2.json
{
    "indicator_types": ["IPv4"]
}

The following JSON object will update the default policy to only process (include) hosts in network 10.0.0.0/8 and not process (exclude) hosts in networks 10.2.100.0/24 and 10.3.100.0/24.

Networks are specified as prefix/length and IPv4 and IPv6 networks are allowed. The policy match order is include then exclude, and the empty list means include all and exclude none respectively.

$ cat policy3.json
{
    "include_networks": ["10.0.0.0/8"],
    "exclude_networks": ["10.2.100.0/24", "10.3.100.0/24"]
}

Access Control

gate.py will run as user gridmeld, group gridmeld using the service unit User and Group options.

Directories for configuration files will be owner root:gridmeld and mode 750. Configuration files will be owner root:root and mode 644.

gridmeld:gridmeld is a powerless user and group that can read the configuration files but cannot modify them.

Create gridmeld user and group

$ sudo bash
# groupadd gridmeld
# useradd -g gridmeld -s /usr/sbin/nologin gridmeld

Create /opt/gridmeld for Config

The following directory structure is created:

• /opt/gridmeld/etc/

  Used for JSON -F config files.

• /opt/gridmeld/ssl/

  Used for SSL server certificates.

• /opt/gridmeld/ssl/private/

  Used for SSL private keys.

# mkdir -p /opt/gridmeld/etc/
# mkdir -p /opt/gridmeld/ssl/private/
# find /opt/gridmeld -type d -exec chown root:gridmeld {} \;
# find /opt/gridmeld -type d -exec chmod 750 {} \;

Sample JSON Config Files

$ cat gate-mm.json
{
    "uri": "https://minemeld.santan.local",
    "username": "gridmeld",
    "password": "paloalto",
    "node": "localDB-1554312231193",
    "verify": "/opt/gridmeld/ssl/mm-cert.pem"
}

$ cat gate-ise.json
{
    "hostname": ["ise-3.santan.local"],
    "nodename": "paloalto04",
    "verify": "/opt/gridmeld/ssl/ise3-ca.pem",
    "cert": "/opt/gridmeld/ssl/private/ise3-paloalto04-nopw.pem"
}

Install JSON Config Files

Copy your JSON files for the --pxgrid and --minemeld -F options into /opt/gridmeld/etc/, for example:

$ sudo bash
# cp gate-ise.json /opt/gridmeld/etc/
# cp gate-mm.json /opt/gridmeld/etc/

Install SSL Certificates and Private Keys

If you have certificate files for the --verify options, copy them into /opt/gridmeld/ssl/, for example:

# cp ise-ca.pem /opt/gridmeld/ssl/
# cp mm-ca.pem /opt/gridmeld/ssl/

If you are using client certificate authentication for pxGrid, copy the SSL private key into /opt/gridmeld/ssl/private/, for example:

# cp ise-paloalto04-nopw.pem /opt/gridmeld/ssl/private/

Set File Owner and Mode

After populating the config directory you should set owner:group and mode for the files using:

# find /opt/gridmeld -type f -exec chown root:root {} \;
# find /opt/gridmeld -type f -exec chmod 644 {} \;

Configure systemd gridmeld Service Unit File

Modify the gridmeld.service unit file Environment options as needed for your environment:

$ cat gridmeld.service
[Unit]
Description=Palo Alto Networks gridmeld Gateway
Documentation=https://github.com/PaloAltoNetworks/gridmeld
After=network.target

[Service]
Environment=PXGRID='--pxgrid -F /opt/gridmeld/etc/gate-ise.json'
Environment=MINEMELD='--minemeld -F /opt/gridmeld/etc/gate-mm.json'
Environment=ARGS='--syslog local0'
Type=simple
Restart=always
RestartSec=10s
User=gridmeld
Group=gridmeld
ExecStart=/usr/local/bin/gate.py $PXGRID $MINEMELD $ARGS

[Install]
WantedBy=multi-user.target

Copy the service unit file in place and verify:

$ sudo cp gridmeld.service /lib/systemd/system

$ systemctl daemon-reload
$ systemctl start gridmeld
$ systemctl status gridmeld

Troubleshooting can be performed by querying the contents of the systemd journal using journalctl:

$ journalctl -n -u gridmeld
$ journalctl -f -u gridmeld

Enable the service to start on boot and verify it is started after a system reboot:

$ systemctl stop gridmeld
$ systemctl enable gridmeld
$ systemctl reboot

Wait for boot, then check the service status:

$ systemctl status gridmeld