PiHole

This Integration is part of the PiHole Pack.#

Pi-hole is a network-level advertisement and Internet tracker blocking application which acts as a DNS sinkhole and optionally a DHCP server, intended for use on a private network. This integration was integrated and tested with version FTL5.2 of PiHole

Configure PiHole on Cortex XSOAR#

Navigate to Settings > Integrations > Servers & Services.
Search for PiHole.
Click Add instance to create and configure a new integration instance.

Parameter	Description	Required
url	Server URL	True
token	Auth Token	False
insecure	Trust any certificate (not secure)	False
proxy	Use system proxy settings	False

Click Test to validate the URLs, token, and connection.

Commands#

You can execute these commands from the Cortex XSOAR CLI, as part of an automation, or in a playbook. After you successfully execute a command, a DBot message appears in the War Room with the command details.

pihole-get-version#

Returns the version of the API

Base Command#

pihole-get-version

Input#

Argument Name	Description	Required

Context Output#

Path	Type	Description
PiHole.Version.version	string	Version info

Command Example#

!pihole-get-version

Context Example#

{
    "PiHole": {
        "Version": {
            "version": 3
        }
    }
}

Human Readable Output#

Results#
version
3

version
3

pihole-get-type#

Returns the backend used by the API (either PHP or FTL)

Base Command#

pihole-get-type

Input#

Argument Name	Description	Required

Context Output#

Path	Type	Description
PiHole.Type.type	string	Type information

Command Example#

!pihole-get-type

Context Example#

{
    "PiHole": {
        "Type": {
            "type": "FTL"
        }
    }
}

Human Readable Output#

Results#
type
FTL

type
FTL

pihole-get-summaryraw#

Gives statistics in raw format (no number formatting applied)

Base Command#

pihole-get-summaryraw

Input#

Argument Name	Description	Required

Context Output#

Path	Type	Description
PiHole.SummaryRaw	string	Summary no formatting

Command Example#

!pihole-get-summaryraw

Context Example#

{
    "PiHole": {
        "SummaryRaw": {
            "ads_blocked_today": 457,
            "ads_percentage_today": 2.387296,
            "clients_ever_seen": 15,
            "dns_queries_all_types": 19143,
            "dns_queries_today": 19143,
            "domains_being_blocked": 85512,
            "gravity_last_updated": {
                "absolute": 1597037232,
                "file_exists": true,
                "relative": {
                    "days": 2,
                    "hours": 5,
                    "minutes": 41
                }
            },
            "privacy_level": 0,
            "queries_cached": 9086,
            "queries_forwarded": 9595,
            "reply_CNAME": 5811,
            "reply_IP": 8696,
            "reply_NODATA": 1664,
            "reply_NXDOMAIN": 1622,
            "status": "disabled",
            "unique_clients": 15,
            "unique_domains": 1551
        }
    }
}

Human Readable Output#

Results#
ads_blocked_today ads_percentage_today clients_ever_seen dns_queries_all_types dns_queries_today domains_being_blocked gravity_last_updated privacy_level queries_cached queries_forwarded reply_CNAME reply_IP reply_NODATA reply_NXDOMAIN status unique_clients unique_domains
457 2.387296 15 19143 19143 85512 file_exists: true
absolute: 1597037232
relative: {"days": 2, "hours": 5, "minutes": 41} 0 9086 9595 5811 8696 1664 1622 disabled 15 1551

ads_blocked_today	ads_percentage_today	clients_ever_seen	dns_queries_all_types	dns_queries_today	domains_being_blocked	gravity_last_updated	privacy_level	queries_cached	queries_forwarded	reply_CNAME	reply_IP	reply_NODATA	reply_NXDOMAIN	status	unique_clients	unique_domains
457	2.387296	15	19143	19143	85512	file_exists: true absolute: 1597037232 relative: {"days": 2, "hours": 5, "minutes": 41}	0	9086	9595	5811	8696	1664	1622	disabled	15	1551

pihole-get-overtimedata10mins#

Data needed for generating the domains/ads over time graph on the Pi-hole web dashboard

Base Command#

pihole-get-overtimedata10mins

Input#

Argument Name	Description	Required

Context Output#

Path	Type	Description
PiHole.OverTimeData10mins	string	Data over last 10mins

Command Example#

!pihole-get-overtimedata10mins

Context Example#

{
    "PiHole": {
        "OverTimeData10mins": {
            "ads_over_time": {
                "1597147500": 2,
                "1597148100": 1,
                "1597148700": 6,
                ...,
                "1597230300": 0
            },
            "domains_over_time": {
                "1597147500": 81,
                "1597148100": 96,
                "1597148700": 85,
                ...,
                "1597230300": 423
            }
        }
    }
}

Human Readable Output#

Results#
ads_over_time domains_over_time
1597147500: 2
1597148100: 1
1597148700: 6
1597230300: 0 1597147500: 81
1597148100: 96
1597148700: 85
1597230300: 423

ads_over_time	domains_over_time
1597147500: 2 1597148100: 1 1597148700: 6 1597230300: 0	1597147500: 81 1597148100: 96 1597148700: 85 1597230300: 423

pihole-get-topitems#

Data needed for generating the Top Domain and Top Advertisers Lists

Base Command#

pihole-get-topitems

Input#

Argument Name	Description	Required
limit	how many entries	Optional

Context Output#

Path	Type	Description
PiHole.TopItems	string	Top Items

Command Example#

!pihole-get-topitems

Context Example#

{
    "PiHole": {
        "TopItems": {
            "top_ads": {
                "api.segment.io": 22,
                "app-measurement.com": 180,
                "cf.iadsdk.apple.com": 9,
                "dhg-logging.us-east-1.elasticbeanstalk.com": 9,
                "iadsdk.apple.com": 64,
                "logging.dhg.myharmony.com": 9,
                "notify.bugsnag.com": 12,
                "pingma.qq.com": 50,
                "static.hotjar.com": 7,
                "www.google-analytics.com": 7
            },
            "top_queries": {
                "agent-gateway-api-prod-eu.traps.paloaltonetworks.com": 1355,
                "ch-xyz.traps.paloaltonetworks.com": 815,
                "dc-xyz.traps.paloaltonetworks.com": 338,
                "gateway.icloud.com": 561,
                "gsp-ssl.ls-apple.com.akadns.net": 387,
                "gsp-ssl.ls.apple.com": 349,
                "xyz": 903,
                "www.google.com": 3153,
                "www.apple.com": 1144
            }
        }
    }
}

Human Readable Output#

Results#
top_ads top_queries
app-measurement.com: 180
iadsdk.apple.com: 64
pingma.qq.com: 50
api.segment.io: 22
notify.bugsnag.com: 12
logging.dhg.myharmony.com: 9
dhg-logging.us-east-1.elasticbeanstalk.com: 9
cf.iadsdk.apple.com: 9
www.google-analytics.com: 7
static.hotjar.com: 7 www.google.com: 3153
agent-gateway-api-prod-eu.traps.paloaltonetworks.com: 1355
xyz: 903
ch-xyz.traps.paloaltonetworks.com: 815
gateway.icloud.com: 561
gsp-ssl.ls-apple.com.akadns.net: 387
gsp-ssl.ls.apple.com: 349
dc-xyz.traps.paloaltonetworks.com: 338

top_ads	top_queries
app-measurement.com: 180 iadsdk.apple.com: 64 pingma.qq.com: 50 api.segment.io: 22 notify.bugsnag.com: 12 logging.dhg.myharmony.com: 9 dhg-logging.us-east-1.elasticbeanstalk.com: 9 cf.iadsdk.apple.com: 9 www.google-analytics.com: 7 static.hotjar.com: 7	www.google.com: 3153 agent-gateway-api-prod-eu.traps.paloaltonetworks.com: 1355 xyz: 903 ch-xyz.traps.paloaltonetworks.com: 815 gateway.icloud.com: 561 gsp-ssl.ls-apple.com.akadns.net: 387 gsp-ssl.ls.apple.com: 349 dc-xyz.traps.paloaltonetworks.com: 338

pihole-get-topclients#

Data needed for generating the Top Clients list

Base Command#

pihole-get-topclients

Input#

Argument Name	Description	Required
limit	how many entries	Optional

Context Output#

Path	Type	Description
PiHole.TopClients	string	Top Clients

Command Example#

!pihole-get-topclients

Context Example#

{
    "PiHole": {
        "TopClients": {
            "top_sources": {
                "192.168.0.1": 497,
                "192.168.0.2": 5964,
                "192.168.0.3": 338,
                "mymachine.local|192.168.0.20": 1627,
                "localhost.localdomain|127.0.0.1": 336
            }
        }
    }
}

Human Readable Output#

Results#
top_sources
192.168.0.2: 5964
mymachine.local|192.168.0.20: 1627
192.168.0.1: 497
192.168.0.3: 338
localhost.localdomain|127.0.0.1: 336

top_sources
192.168.0.2: 5964 mymachine.local\|192.168.0.20: 1627 192.168.0.1: 497 192.168.0.3: 338 localhost.localdomain\|127.0.0.1: 336

pihole-get-forward-destinations#

Shows number of queries that have been forwarded and the target

Base Command#

pihole-get-forward-destinations

Input#

Argument Name	Description	Required

Context Output#

Path	Type	Description
PiHole.ForwardDestinations	string	Fowarding destinations

Command Example#

!pihole-get-forward-destinations

Context Example#

{
    "PiHole": {
        "ForwardDestinations": {
            "forward_destinations": {
                "1.1.1.2": 24.77,
                "1.1.1.3": 25.42,
                "blocklist|blocklist": 2.39,
                "cache|cache": 47.48
            }
        }
    }
}

Human Readable Output#

Results#
forward_destinations
blocklist|blocklist: 2.39
cache|cache: 47.48
1.1.1.3: 25.42
1.0.0.3: 24.77

forward_destinations
blocklist\|blocklist: 2.39 cache\|cache: 47.48 1.1.1.3: 25.42 1.0.0.3: 24.77

pihole-get-query-types#

Shows number of queries that the Pi-hole’s DNS server has processed

Base Command#

pihole-get-query-types

Input#

Argument Name	Description	Required

Context Output#

Path	Type	Description
PiHole.QueryTypes	string	Query types

Command Example#

!pihole-get-query-types

Context Example#

{
    "PiHole": {
        "QueryTypes": {
            "querytypes": {
                "A (IPv4)": 75.52,
                "AAAA (IPv6)": 15.08,
                "ANY": 0,
                "DNSKEY": 0,
                "DS": 0,
                "MX": 0,
                "NAPTR": 0,
                "OTHER": 0,
                "PTR": 3.13,
                "RRSIG": 0,
                "SOA": 5.19,
                "SRV": 0.6,
                "TXT": 0.48
            }
        }
    }
}

Human Readable Output#

Results#
querytypes
A (IPv4): 75.52
AAAA (IPv6): 15.08
ANY: 0
SRV: 0.6
SOA: 5.19
PTR: 3.13
TXT: 0.48
NAPTR: 0
MX: 0
DS: 0
RRSIG: 0
DNSKEY: 0
OTHER: 0

querytypes
A (IPv4): 75.52 AAAA (IPv6): 15.08 ANY: 0 SRV: 0.6 SOA: 5.19 PTR: 3.13 TXT: 0.48 NAPTR: 0 MX: 0 DS: 0 RRSIG: 0 DNSKEY: 0 OTHER: 0

pihole-get-all-queries#

Get DNS queries data

Base Command#

pihole-get-all-queries

Input#

Argument Name	Description	Required

Context Output#

Path	Type	Description
PiHole.AllQueries	string	All Queries (a lot of data)

Command Example#

!pihole-get-all-queries

Human Readable Output#

This command will return all queries. Its a big list in a file.

pihole-status#

Show status of pihole action (enabled - disabled)

Base Command#

pihole-status

Input#

Argument Name	Description	Required

Context Output#

Path	Type	Description
PiHole.Status	string	Status

Command Example#

!pihole-status

Context Example#

{
    "PiHole": {
        "Status": {
            "status": "disabled"
        }
    }
}

Human Readable Output#

Results#
status
disabled

status
disabled

pihole-enable#

Enable Pi-hole ad blocking

Base Command#

pihole-enable

Input#

Argument Name	Description	Required

Context Output#

Path	Type	Description
PiHole.Enable	string	Enabled blocking

Command Example#

!pihole-enable

Context Example#

{
    "PiHole": {
        "Enable": {
            "status": "enabled"
        }
    }
}

Human Readable Output#

Results#
status
enabled

status
enabled

pihole-disable#

used to disable pihole for certain amount of time

Base Command#

pihole-disable

Input#

Argument Name	Description	Required
time	Time in seconds for blocking to be disabled	Optional

Context Output#

Path	Type	Description
PiHole.Disable	string	Disabled

Command Example#

!pihole-disable

Context Example#

{
    "PiHole": {
        "Disable": {
            "status": "disabled"
        }
    }
}

Human Readable Output#

Results#
status
disabled

status
disabled

pihole-get-versions#

Show versions of all components

Base Command#

pihole-get-versions

Input#

Argument Name	Description	Required

Context Output#

Path	Type	Description
PiHole.Versions	string	Version info

Command Example#

!pihole-get-versions

Context Example#

{
    "PiHole": {
        "Versions": {
            "FTL_branch": "master",
            "FTL_current": "v5.2",
            "FTL_latest": "v5.2",
            "FTL_update": false,
            "core_branch": "master",
            "core_current": "v5.1.2",
            "core_latest": "v5.1.2",
            "core_update": false,
            "web_branch": "master",
            "web_current": "v5.1.1",
            "web_latest": "v5.1.1",
            "web_update": false
        }
    }
}

Human Readable Output#

Results#
FTL_branch FTL_current FTL_latest FTL_update core_branch core_current core_latest core_update web_branch web_current web_latest web_update
master v5.2 v5.2 false master v5.1.2 v5.1.2 false master v5.1.1 v5.1.1 false

FTL_branch	FTL_current	FTL_latest	FTL_update	core_branch	core_current	core_latest	core_update	web_branch	web_current	web_latest	web_update
master	v5.2	v5.2	false	master	v5.1.2	v5.1.2	false	master	v5.1.1	v5.1.1	false

pihole-get-topclientsblocked#

Shows the top clients being blocked

Base Command#

pihole-get-topclientsblocked

Input#

Argument Name	Description	Required

Context Output#

Path	Type	Description
PiHole.TopClientsBlocked	string	Top blocked clients

Command Example#

!pihole-get-topclientsblocked

Context Example#

{
    "PiHole": {
        "TopClientsBlocked": null
    }
}

Human Readable Output#

Results#
No entries.

pihole-get-cache-info#

Show cache info

Base Command#

pihole-get-cache-info

Input#

Argument Name	Description	Required

Context Output#

Path	Type	Description
PiHole.CacheInfo	string	Cache info

Command Example#

!pihole-get-cache-info

Context Example#

{
    "PiHole": {
        "CacheInfo": {
            "cacheinfo": {
                "cache-inserted": 99,
                "cache-live-freed": 0,
                "cache-size": 10000
            }
        }
    }
}

Human Readable Output#

Results#
cacheinfo
cache-size: 10000
cache-live-freed: 0
cache-inserted: 99

cacheinfo
cache-size: 10000 cache-live-freed: 0 cache-inserted: 99

pihole-get-recent-blocked#

Show most recent blocked domain

Base Command#

pihole-get-recent-blocked

Input#

Argument Name	Description	Required

Context Output#

Path	Type	Description
PiHole.RecentBlocked	string	Recently blocked

Command Example#

!pihole-get-recent-blocked

Context Example#

{
    "PiHole": {
        "RecentBlocked": {
            "Data": "abc.xyz.com"
        }
    }
}

Human Readable Output#

Results#
Data
abc.xyz.com

Data
abc.xyz.com

pihole-get-overTimeDataQueryTypes#

Get data over time per query types

Base Command#

pihole-get-overTimeDataQueryTypes

Input#

Argument Name	Description	Required

Context Output#

Path	Type	Description
PiHole.OverTimeDataQueryTypes	string	Over time query types

Command Example#

!pihole-get-overTimeDataQueryTypes

Context Example#

{
    "PiHole": {
        "OverTimeDataQueryTypes": {
            "over_time": {
                "1597147500": [
                    87.34,
                    12.66
                ],
                "1597148100": [
                    91.67,
                    8.33
                ],
                "1597148700": [
                    90.12,
                    9.88
                ],
                "1597230300": [
                    63.33,
                    36.67
                ]
            }
        }
    }
}

Human Readable Output#

Results#
over_time
1597147500: 87.34,
12.66
1597148100: 91.67,
8.33
1597148700: 90.12,
9.88
1597230300: 63.33,
36.67

over_time
1597147500: 87.34, 12.66 1597148100: 91.67, 8.33 1597148700: 90.12, 9.88 1597230300: 63.33, 36.67

pihole-get-client-names#

Get client names

Base Command#

pihole-get-client-names

Input#

Argument Name	Description	Required

Context Output#

Path	Type	Description
PiHole.ClientNames	string	Client names

Command Example#

!pihole-get-client-names

Context Example#

{
    "PiHole": {
        "ClientNames": {
            "clients": [
                {
                    "ip": "192.168.0.1",
                    "name": "mymachine1.local"
                },
                {
                    "ip": "192.168.0.2",
                    "name": "mymachine2.local"
                },
                {
                    "ip": "192.168.0.3",
                    "name": "mymachine3.local"
                }
            ]
        }
    }
}

Human Readable Output#

Results#
clients
{'name': 'mymachine1.local', 'ip': '192.168.0.1'},
{'name': 'mymachine2.local', 'ip': '192.168.0.2'},
{'name': 'mymachine3.local', 'ip': '192.168.0.3'}

pihole-get-over-time-data-clients#

Get over time data clients

Base Command#

pihole-get-over-time-data-clients

Input#

Argument Name	Description	Required

Context Output#

Path	Type	Description
PiHole.OverTimeDataClients	string	Over time client data

Command Example#

!pihole-get-over-time-data-clients

Context Example#

{
    "PiHole": {
        "OverTimeDataClients": {
            "over_time": {
                "1597147500": [
                    0,
                    24,
                    41,
                    1,
                    2,
                    10,
                    2,
                    1,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0
                ],
                "1597148100": [
                    0,
                    50,
                    33,
                    0,
                    3,
                    8,
                    1,
                    1,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0
                ],
                "1597148700": [
                    0,
                    30,
                    5,
                    1,
                    3,
                    21,
                    0,
                    0,
                    25,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0
                ],
                "1597230300": [
                    367,
                    38,
                    0,
                    16,
                    2,
                    0,
                    2,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0
                ]
            }
        }
    }
}

Human Readable Output#

Results#
over_time
1597147500: 0,
24,
41,
1,
2,
10,
2,
1,
0,
0,
0,
0,
0,
0,
0
1597148100: 0,
50,
33,
0,
3,
8,
1,
1,
0,
0,
0,
0,
0,
0,
0
1597148700: 0,
30,
5,
1,
3,
21,
0,
0,
25,
0,
0,
0,
0,
0,
0
1597230300: 367,
38,
0,
16,
2,
0,
2,
0,
0,
0,
0,
0,
0,
0,
0

pihole-list-management#

Manage lists. Add or remove items from lists

Base Command#

pihole-list-management

Input#

Argument Name	Description	Required
domain	Domain to be added or removed	Optional
action	add or sub	Optional
list	which list to interact with	Required

Context Output#

Path	Type	Description
PiHole.List	string	Lists

Command Example#

!pihole-list-management list=white action=add domain=paloaltonetworks.com

Context Example#

{
    "PiHole": {
        "List": {
            "message": "Added paloaltonetworks.com",
            "success": true
        }
    }
}

Human Readable Output#

Results#
message success
Added paloaltonetworks.com true

pihole-get-list#

Get all available lists from Pihole

Base Command#

pihole-get-list

Input#

Argument Name	Description	Required
list	which list to get	Required

Context Output#

Path	Type	Description
PiHole.Lists	string	get a list data

Command Example#

!pihole-get-list list=white

Context Example#

{
    "PiHole": {
        "Lists": {
            "data": [
                {
                    "comment": null,
                    "date_added": 1593758659,
                    "date_modified": 1593758659,
                    "domain": "www.googleadservices.com",
                    "enabled": 1,
                    "groups": [
                        0
                    ],
                    "id": 2,
                    "type": 0
                },
                {
                    "comment": null,
                    "date_added": 1593758671,
                    "date_modified": 1593758671,
                    "domain": "www.googletagmanager.com",
                    "enabled": 1,
                    "groups": [
                        0
                    ],
                    "id": 3,
                    "type": 0
                },
                {
                    "comment": null,
                    "date_added": 1594876318,
                    "date_modified": 1594876318,
                    "domain": "google.com",
                    "enabled": 1,
                    "groups": [
                        0
                    ],
                    "id": 8,
                    "type": 0
                }
            ]
        }
    }
}

Human Readable Output#

Results#
data
{'id': 2, 'type': 0, 'domain': 'www.googleadservices.com', 'enabled': 1, 'date_added': 1593758659, 'date_modified': 1593758659, 'comment': None, 'groups': [0]},
{'id': 3, 'type': 0, 'domain': 'www.googletagmanager.com', 'enabled': 1, 'date_added': 1593758671, 'date_modified': 1593758671, 'comment': None, 'groups': [0]},
{'id': 8, 'type': 0, 'domain': 'google.com', 'enabled': 1, 'date_added': 1594876318, 'date_modified': 1594876318, 'comment': None, 'groups': [0]}