Fireshield (Hydra transport)

Hydra protocol feature

General information

The Unified SDK offers domain categorization functionality, enabling you to classify domains and perform specific actions on them while the traffic passes through a VPN connection.

Fireshield configuration file saves DATA_FOLDER/unified-sdk/fireshield in the following files:

• fireshield - contains a fireshield config that will be used by Hydra

• unsafefraud, unsafespam, unsafeuntrusted, safe, etc. - this files contains domains for any possible category (the category name must match the file name) in fireshield config

Possible fireshield category types

• bypass - It means that website go to the Internet behind, without using the VPN tunnel

• vpn - It means that website go to the Internet through the VPN tunnel

• proxy_peer - It means that website go to the Internet through the VPN tunnel with some addition Hydra implementation

• block_dns - It means that website will be blocked

• block_alert_page - It means that website will be blocked and tunned alert page will be displayed

How to manual setup a fireshield on the client side

Create/change a fireshield configuration file named "fireshield" in "DATA_FOLDER/unified-sdk/fireshield"

File structure

{
    "enabled": true,
    "services": [
        "example_service_name",
        "example_service_name1"
    ],
    "alert_page": {
        "domain": "example.com",
        "path": "test/example_safe_zone"
    },
    "categories": [
        {
            "category": "unsafe:untrusted",
            "type": "block_dns"
        },
        {
            "category": "unsafe:spam",
            "type": "block_alert_page"
        },
        {
            "category": "safe",
            "type": "proxy_peer"
        },
        {
            "category": "unsafe:fraud",
            "type": "bypass"
        }
    ],
    "domains": {
        "unsafe:untrusted": [
            domain1.com,
            domain2.net
        ],
        "unsafe:spam": [
            domain3.com,
            domain4.net
        ],
        "unsafe:fraud": [
            domain5.com,
            domain6.net
        ]
    }
}

Structure description

• "enabled" - A value indicating whether to use Fireshield

• "services" - Contains the names of some databases with compromised domains

• "alert_page" - Contains the alert page definition (e.g. "https://foo.bar.com/security/safe_zone") where the user will be redirected if he tries to access the site marked as block_alert_page

  • "domain" - The domain of the alert page, for instance "foo.bar.com"

  • "path" - The path of the alert page, for instance "security/safe_zone"

• "categories" - Describes the client Fireshield categories

  • "category" - The category name, name as you want

  • "type" - The Fireshield category type. Fireshield supports the following types

    • bypass - It means that website go to the Internet behind, without using the VPN tunnel

    • vpn - It means that website go to the Internet through the VPN tunnel

    • proxy_peer - It means that website go to the Internet through the VPN tunnel with some addition Hydra implementation

    • block_dns - It means that website will be blocked

    • block_alert_page - It means that website will be blocked and tunned alert page will be displayed

• "domains" - Contains the list of domains splitted by category

  • "category_name_from_categories" - Contains the list of domains which will be tracked

How to setup a fireshield configuration on the client side using SDK

BuildFireshieldConfig

Builds the fireshield configuration. Replace existing configuration or create new one if it does not exist.

var request = new BuildFireshieldConfigRequest()
{
    Enabled = true,
    AlertPageDomain = "test.net",
    AlertPagePath = "safe_zone.html",
    Services = new List<string> { "test_service", "test_service2" },
    Categories = new List<Category>(),
    CategoryRules = new List<CategoryRule>(),
};

var response = await sdk.BuildFireshieldConfig(request).ConfigureAwait(false);

EnableFireshield

Enables fireshield feature.

var response = await sdk.EnableFireshield().ConfigureAwait(false);

DisableFireshield

Disables fireshield feature.

var response = await sdk.DisableFireshield().ConfigureAwait(false);

For EnableFireshield/DisableFireshield SDK returns FireshieldConfigurationException if configuration does not exist.

GetCurrentFireshieldConfig

Returns current fireshield configuration if exist or empty string.

var response = await sdk.GetCurrentFireshieldConfig().ConfigureAwait(false);

DeleteFireshieldConfig

Deletes the fireshield configuration and all related files.

var response = await sdk.DeleteFireshieldConfig().ConfigureAwait(false);

How to setup a custom fireshield configuration on the client side using SDK

Usually "domains" or "categories" fields in fireshield configuration do not contain very many entries. But in cases when these fields contain a lot of entries it will be a good way to build custom fireshield configuration.

First of all needs to create files which contain the "domains"/"categories" entries.

For categories it should be "fireshield-var-categories".

For category rules it should be "fireshield-var-domains".

CreateCategoriesFile

Creates the "fireshield-var-categories" file with categories. Use this if categories contain a lot of entries.

var categoriesFileContent =
@"[
	{
		""category"": ""unsafe:ads"",
		""type"": ""block_dns""
	},
	...
	{
		""category"": ""safe"",
		""type"": ""proxy_peer""
	}
]";
        
var request = new CreateCategoriesFileRequest
{
    CategoriesContent = categoriesFileContent ,
};

var response = await sdk.CreateCategoriesFile(request).ConfigureAwait(false);

CreateCategoryRulesFile

Creates the "fireshield-var-domains" file with category rules. Use this if category rules contain a lot of entries.

var categoryRulesFileContent =
@"{
       ""safe"": [
           ""domain_1"",
           ...
           ""domain_10000""
       ],
       ""unsafe:ads"": [
            ""domain_1"",
            ...
            ""domain_10000""
       ],
       .......................
       ,
       ""unsafe:trackers"": [
            ""domain_1"",
            ...
            ""domain_10000""
       ]
}";
        
var request = new CreateCategoryRulesFileRequest
{
    CategoryRulesContent = categoryRulesFileContent,
};

var response = await sdk.CreateCategoryRulesFile(request).ConfigureAwait(false);

After creating files needs to build a custom fireshield configuration. Custom fireshield configuration should looks like this:

{
	"alert_page": {
		"domain": "your_domain",
		"path": "your_path"
	},
	"categories": "##fireshield-var-categories##",
	"domains": "##fireshield-var-domains##",
	"enabled": "true",
	"services": [
		"your_services"
	]
}

ApplyCustomFireshieldConfig

Applies the custom fireshield configuration.

var request = new ApplyCustomFireshieldConfigRequest()
{
    Enabled = true,
    AlertPageDomain = "test.net",
    AlertPagePath = "safe_zone.html",
    Services = new List<string> { "test_service", "test_service2" },
    Categories = "##fireshield-var-categories##", // Use this if categories contains a lots of entries
    CategoryRules = "##fireshield-var-domains##", // Use this if category rules contain a lots of entries
};

var response = await sdk.ApplyCustomFireshieldConfig(request).ConfigureAwait(false);

If the file "##fireshield-var-categories##" or "##fireshield-var-domains##" was provided to SDK but does not exist that SDK returns FireshieldConfigurationException.