Safelist (Whitelist) File – JSON Format

The safelist is stored in json format, an industry standard for sharing data. Here’s a small part of the top of the default safelist:

[
{
"Name": "8075",
"Type": "asn",
"Modules": [
{
"Name": "Beacons",
"Src": false,
"Dst": true
}
],
"Comment": "Microsoft patching and time servers"
},
{
"Name": "41231",
"Type": "asn",
"Modules": [
{
"Name": "Beacons",
"Src": false,
"Dst": true
}
],
"Comment": "Ubuntu patching servers"
},
...

 

You have the ability to edit this file to add new entries, take out existing entries, or modify entries. If you do, here are a few notes about the formatting in this file:

You must use double quotes, not single quotes, backquotes or “smart quotes” as used in word processors for all strings. For example, “Name” and “8075” from above are valid; ‘Name’ and `8075` are not.

Whenever using true, false, or null as values, these must be all lowercase.

Inside each matched pair of left and right square brackets (“[” and “]”, json lists), and inside each matched pair of curly braces (“{” and “}”, json dictionaries), the entries are separated by commas, but you don’t use a comma after the final entry. For example:

 {
"Name": "Beacons",
"Src": false,
"Dst": true
}

 

Most Linux distributions and the Mac OS offer a tool called jq (“json query”) that allows you to extract data from and modify json files. It’s not commonly installed by default, but should be available in your package manager. Once installed you can do the following:

To see the full contents in pretty-printed format (like the example above where entries are indented according to how deep they are), use:

cat edited-safelist.json | jq . | less

 

To check whether a json file is in a valid format, run:

$ cat edited-safelist.json | jq . >/dev/null
$

 

When you’re returned to a prompt directly, that means the format appears correct. If the file is not valid json, such as this one where I used single quotes instead of double quotes:

$ cat malformed-safelist.json | jq . >/dev/null
parse error: Invalid numeric literal at line 1, column 16
$

 

you’ll get back some kind of error.

The default json output format (pretty-printing, as seen above) takes a lot of lines to display, especially when you have a large safelist. To give each safelist entry a single line run the following (all on one line, even if wrapped in this document):

( echo '[' ; cat edited-safelist.json | jq -c '.[]' | sed -e '$!s/$/,/' ; echo ']' ) >safelist-perline.json

 

The safelist-perline.json contains the same content and is still a valid json file, but shows the safelist entries one per line, such as:

[
{"Name":"8075","Type":"asn","Modules":[{"Name":"Beacons","Src":false,"Dst":true}],"Comment":"Microsoft patching and time servers"},
{"Name":"41231","Type":"asn","Modules":[{"Name":"Beacons","Src":false,"Dst":true}],"Comment":"Ubuntu patching servers"},
{"Name":"16625","Type":"asn","Modules":[{"Name":"Beacons","Src":false,"Dst":true}],"Comment":"Akamai CDN"},
]

 

Direct Link to this FAQ Item: https://portal.activecountermeasures.com/support/faq/?Display_FAQ=859

---