PiHole

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

  1. Navigate to Settings > Integrations > Servers & Services.
  2. Search for PiHole.
  3. Click Add instance to create and configure a new integration instance.
ParameterDescriptionRequired
urlServer URLTrue
tokenAuth TokenFalse
insecureTrust any certificate (not secure)False
proxyUse system proxy settingsFalse
  1. Click Test to validate the URLs, token, and connection.

Commands

You can execute these commands from the Demisto 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 NameDescriptionRequired

Context Output

PathTypeDescription
PiHole.Version.versionstringVersion info

Command Example

!pihole-get-version

Context Example

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

Human Readable Output

Results

version
3

pihole-get-type


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

Base Command

pihole-get-type

Input

Argument NameDescriptionRequired

Context Output

PathTypeDescription
PiHole.Type.typestringType information

Command Example

!pihole-get-type

Context Example

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

Human Readable Output

Results

type
FTL

pihole-get-summaryraw


Gives statistics in raw format (no number formatting applied)

Base Command

pihole-get-summaryraw

Input

Argument NameDescriptionRequired

Context Output

PathTypeDescription
PiHole.SummaryRawstringSummary 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_todayads_percentage_todayclients_ever_seendns_queries_all_typesdns_queries_todaydomains_being_blockedgravity_last_updatedprivacy_levelqueries_cachedqueries_forwardedreply_CNAMEreply_IPreply_NODATAreply_NXDOMAINstatusunique_clientsunique_domains
4572.38729615191431914385512file_exists: true
absolute: 1597037232
relative: {"days": 2, "hours": 5, "minutes": 41}
0908695955811869616641622disabled151551

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 NameDescriptionRequired

Context Output

PathTypeDescription
PiHole.OverTimeData10minsstringData 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_timedomains_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 NameDescriptionRequired
limithow many entriesOptional

Context Output

PathTypeDescription
PiHole.TopItemsstringTop 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_adstop_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 NameDescriptionRequired
limithow many entriesOptional

Context Output

PathTypeDescription
PiHole.TopClientsstringTop 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

pihole-get-forward-destinations


Shows number of queries that have been forwarded and the target

Base Command

pihole-get-forward-destinations

Input

Argument NameDescriptionRequired

Context Output

PathTypeDescription
PiHole.ForwardDestinationsstringFowarding 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

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 NameDescriptionRequired

Context Output

PathTypeDescription
PiHole.QueryTypesstringQuery 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

pihole-get-all-queries


Get DNS queries data

Base Command

pihole-get-all-queries

Input

Argument NameDescriptionRequired

Context Output

PathTypeDescription
PiHole.AllQueriesstringAll 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 NameDescriptionRequired

Context Output

PathTypeDescription
PiHole.StatusstringStatus

Command Example

!pihole-status

Context Example

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

Human Readable Output

Results

status
disabled

pihole-enable


Enable Pi-hole ad blocking

Base Command

pihole-enable

Input

Argument NameDescriptionRequired

Context Output

PathTypeDescription
PiHole.EnablestringEnabled blocking

Command Example

!pihole-enable

Context Example

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

Human Readable Output

Results

status
enabled

pihole-disable


used to disable pihole for certain amount of time

Base Command

pihole-disable

Input

Argument NameDescriptionRequired
timeTime in seconds for blocking to be disabledOptional

Context Output

PathTypeDescription
PiHole.DisablestringDisabled

Command Example

!pihole-disable

Context Example

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

Human Readable Output

Results

status
disabled

pihole-get-versions


Show versions of all components

Base Command

pihole-get-versions

Input

Argument NameDescriptionRequired

Context Output

PathTypeDescription
PiHole.VersionsstringVersion 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_branchFTL_currentFTL_latestFTL_updatecore_branchcore_currentcore_latestcore_updateweb_branchweb_currentweb_latestweb_update
masterv5.2v5.2falsemasterv5.1.2v5.1.2falsemasterv5.1.1v5.1.1false

pihole-get-topclientsblocked


Shows the top clients being blocked

Base Command

pihole-get-topclientsblocked

Input

Argument NameDescriptionRequired

Context Output

PathTypeDescription
PiHole.TopClientsBlockedstringTop 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 NameDescriptionRequired

Context Output

PathTypeDescription
PiHole.CacheInfostringCache 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

pihole-get-recent-blocked


Show most recent blocked domain

Base Command

pihole-get-recent-blocked

Input

Argument NameDescriptionRequired

Context Output

PathTypeDescription
PiHole.RecentBlockedstringRecently blocked

Command Example

!pihole-get-recent-blocked

Context Example

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

Human Readable Output

Results

Data
abc.xyz.com

pihole-get-overTimeDataQueryTypes


Get data over time per query types

Base Command

pihole-get-overTimeDataQueryTypes

Input

Argument NameDescriptionRequired

Context Output

PathTypeDescription
PiHole.OverTimeDataQueryTypesstringOver 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

pihole-get-client-names


Get client names

Base Command

pihole-get-client-names

Input

Argument NameDescriptionRequired

Context Output

PathTypeDescription
PiHole.ClientNamesstringClient 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 NameDescriptionRequired

Context Output

PathTypeDescription
PiHole.OverTimeDataClientsstringOver 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 NameDescriptionRequired
domainDomain to be added or removedOptional
actionadd or subOptional
listwhich list to interact withRequired

Context Output

PathTypeDescription
PiHole.ListstringLists

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

messagesuccess
Added paloaltonetworks.comtrue

pihole-get-list


Get all available lists from Pihole

Base Command

pihole-get-list

Input

Argument NameDescriptionRequired
listwhich list to getRequired

Context Output

PathTypeDescription
PiHole.Listsstringget 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]}