API Overview

On this page

This page shows the general details of the ASP-WAF firewall's data state and how you can use the API to access it. This sample will visualize the data in several charts allowing you to inspect some of the available data in the framework via the firewall's native reporting interfaces and methods.

API & Data Overview

There are several ways to access these firewall state objects and this page demonstrates how this is done. The charts, data grids as well as the code behind files on this page showcase the API and show some of the data available. The data rendered on this page is extracted from the firewall management object and contains no 3rd party plug-in's or data subscription.

Incidents

About this sample

The following code is rendered from the partial view used to render the chart showing the incidents that have been recorded over time.

About the data

All data shown are collected without 3rd party services and use the firewall as model to render the data. . This can be done in an API endpoint and have faster page performance. However this is done to demonstrate using the firewall as a data source.

The rendered data is extracted from the IIncidentDatabase interface. The method used returns a read-only list of IIncident objects that is used for this reporting sample.

Depending on your configuration a blocked user can be blocked for a duration (TimeSpan) from few minutes to years. The users active incident is based on the fact that the incident has not yet expired.

The code used to render the chart

The code below uses jqxWidgets for generating the charts, you are able to render the data with any framework you choose.

@inject Walter.Web.FireWall.IFireWall _fireWall
@{
    var data = _fireWall.Incidents.All(distinct:true,limitTo:TimeSpan.FromDays(365))                    
                    .GroupBy(groupOn => groupOn.Reported.Date)
                    .Select(source => new
                    {
                        date = source.Key,
                        active = source.Count(w => w.Expires > DateTime.Now),
                        expired = source.Count(w => w.Expires < DateTime.Now)
                        
                                      
                    }).OrderBy(order=>order.date)
    .ToArray();
    }

    <!--Placeholder for the chart-->
    <div id="jqxIncidentChart" class="jqxChart">
    </div>


    <script type="text/javascript">

    document.addEventListener('DOMContentLoaded', (event) => {

        var dataIncident = '@Html.Raw(Newtonsoft.Json.JsonConvert.SerializeObject(data))';
        var sourceIncidents =
        {
            datatype: "json",
            datafields: [
                { name: 'date' },
                { name: 'active' },
                { name: 'expired' },
            ],
            localdata: dataIncident
        };

        var dataAdapterIncidents = new $.jqx.dataAdapter(sourceIncidents);

        var months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];

        //allow for a rendering method of chart the tooltip giving some extra details
        var jqxIncidentFormatFn = function (value, itemIndex, serie, group, categoryValue, categoryAxis) {
            var dataItem = dataAdapterIncidents.records[itemIndex];
            return "on " + dataItem.date + " there where " + (dataItem.active + dataItem.expired) + " incidents";
        };

        var incidentChartSettings = {
            title: "Incidents over time",
            description: "(Recorded @data.Sum(count=>count.active+count.expired) incidents in @((int)(data.Max(max=>max.date)-data.Min(min=>min.date)).TotalDays) days)",
            enableAnimations: true,
            showLegend: true,
            padding: { left: 5, top: 5, right: 5, bottom: 5 },
            titlePadding: { left: 30, top: 0, right: 0, bottom: 10 },
            source: dataAdapterIncidents,
            xAxis:
            {
                dataField: 'date',
                formatFunction: function (value) {
                    return value.getDate() + '-' + months[value.getMonth()] + '-' + value.getFullYear();
                },
                type: 'date',
                baseUnit: 'day',
                minValue: '@data.Min(min=>min.date).ToString("dd-MM-yyyy")',
                maxValue: '@data.Max(max=>max.date).ToString("dd-MM-yyyy")',
                valuesOnTicks: true,
                tickMarks: {
                    visible: true,
                    interval: 20,
                    color: '#BCBCBC'
                },
                unitInterval: 5,
                gridLines: {
                    visible: true,
                    interval: 5,
                    color: '#BCBCBC'
                },
                labels: {
                    angle: -45,
                    rotationPoint: 'topright',
                    offset: { x: 0, y: -25 }
                }
            },
            valueAxis:
            {

                visible: true,
                title: { text: 'Incident on day<br>' },
                tickMarks: { color: '#BCBCBC' }
            },
            colorScheme: 'scheme06',
            seriesGroups:[{
                    toolTipFormatFunction: jqxIncidentFormatFn,
                    type: 'line',
                    series: [
                        { dataField: 'active', displayText: 'active' },
                        { dataField: 'expired', displayText: 'expired' }
                    ]}
            ]};

        $('#jqxIncidentChart').jqxChart(incidentChartSettings);
        $('#jqxIncidentChart').jqxChart('hideSerie', 0, 0, NaN);
    });
    </script>

This chart demonstrates the frequency of attacks to this website in real-time by querying the firewall's Incidents data.

Malicious Activity

About this sample

The following code is rendered from the partial view used to render the chart showing malicious activity and attack vector that have been recorded over time.

About the data

All data shown is collected without 3rd party services and use the firewall as model to render the data. This can be done in an API endpoint and have faster page performance. However this is done to demonstrate using the firewall as a data source.

The rendered data is extracted from the IIncidentDatabase interface. The method used returns a read-only list of IIncident objects that generates this reporting sample.

The users performing malicious activities get discovered by the firewall's Guard Modules and the Rule Engine. You can view the blocking reasons in detail on the IIncident.Reason IIncident.Reason property containing an enumerable value that allows for simple parsing.

The code used to render the chart

The code below uses jqxWidgets for generating the charts, you are able to render the data with any framework you choose.


@using Walter.Web.FireWall.Infrastructure
@inject Walter.Web.FireWall.IFireWall _fireWall
@{
    var data = _fireWall.Incidents.All()
                                  .Where(where => where.Reported > DateTime.Now.AddYears(-1)).ToArray();
    
 
    var chartData= data.GroupBy(groupOn => string.Join(", ",groupOn.Reason.GetFlags()))
                    .Select(source => new{
                        reason = source.Key,
                        share = (source.Count() / (double)data.Length).ToString("P1"),
                        count= source.Count()
                     })
                    .OrderByDescending(o=>o.count)
                    .ToArray();

    var firstDate = data.Min(s => s.Reported).ToString("ddd dd MMM yy");
    var count=data.Count();
}
<!--Placeholder for the chart of https://www.jqwidgets.com/-->
<div id='jqxMaliciouseAcivityChart' class="jqxChart">
</div>

<script>

    document.addEventListener('DOMContentLoaded', (event) => {
        var dataMaliciouseAcivity = '@Html.Raw(Newtonsoft.Json.JsonConvert.SerializeObject(chartData))';
        var sourceMaliciouseAcivity =
        {
            datatype: "json",
            datafields: [
                { name: 'reason' },
                { name: 'share' },
                { name: 'count' }
            ],
            localdata: dataMaliciouseAcivity
        };

        var dataMaliciouseAcivityAdapter = new $.jqx.dataAdapter(sourceMaliciouseAcivity);
        var jqxMaliciouseAcivitySettingsFn = function (value, itemIndex, serie, group, categoryValue, categoryAxis) {
            var dataItem = dataMaliciouseAcivityAdapter.records[itemIndex];
            return dataItem.share + "<br/> in " + dataItem.count + " we detected " + dataItem.reason ;
        };
      
        var jqxMaliciouseAcivitySettings = {
            title: "Malicious activity",
            description:'(@string.Concat(chartData.Length, " Guard-Actions categories triggered ",count.ToString("N0")," times"))',
            enableAnimations: true,
            showLegend: false,
            colorScheme: 'scheme06',
            showBorderLine: true,
            legendLayout: { left: 10, top: 270, width: 300, height: 20, flow: 'horizontal' },
            padding: { left: 5, top: 5, right: 5, bottom: 5 },
            titlePadding: { left: 0, top: 0, right: 0, bottom: 10 },
            source: dataMaliciouseAcivityAdapter,
            seriesGroups:[{
                type: 'pie',
                showLabels: true,
                series:[{
                    toolTipFormatFunction: jqxMaliciouseAcivitySettingsFn,
                    dataField: 'share',
                    displayText: 'reason',
                    labelRadius: 90,
                    initialAngle: 15   ,
                    radius: 70      ,
                    centerOffset: 0    
                }]
            }]
        };

        // select the chartContainer DIV element and render the chart in it.
        $('#jqxMaliciouseAcivityChart').jqxChart(jqxMaliciouseAcivitySettings);
    });
</script>

The firewall uses a rule engine with Guard Modules that protect your web application. The firewall comes with default rules that you can configure was well as allows you to add your own rules.

ISP WHOIS

About this sample

The following code is rendered from the partial view used to render the chart showing the internet service providers (ISP) that have been facilitating the malicious activity.

About the data

All data shown is collected without 3rd party services and use the firewall as model to render the data. This can be done in an API endpoint and have faster page performance. However this is done to demonstrate using the firewall as a data source.

The rendered data is extracted from the IIncidentDatabase interface. The method used returns a read-only list of IIncident objects that have a property named IIncident.Whois This property is used for this reporting sample by grouping on these ISP's and counting the penetration attempts my by users, using this ISP.

The code used to render the chart

The code below uses jqxWidgets for generating the charts, you are able to render the data with any framework you choose.

@inject Walter.Web.FireWall.IFireWall _fireWall
@{
    var data = _fireWall.Incidents.All()
                    .Where(where => where.Whois is not null).ToArray();

    var chartData = data.Where(where => !string.IsNullOrEmpty(where.Whois!.Organization))
                    .GroupBy(groupOn => groupOn.Whois!.Organization)
                    .Select(source => new
                    {
                        Name = source.Key,
                        Share = (source.Count()/(double)data.Length).ToString("P1"),
                        Count= source.Count(),
                        From=source.Min(m=>m.Reported).ToString("ddd dd.MMM.yy"),
                        Till = source.Max(m => m.LastTriggered).ToString("ddd dd.MMM.yy"),

                    }).ToArray().OrderByDescending(o=>o.Count).Take(10);

}
<!--Placeholder for the chart-->
<div id="jqxWhoisChart" class="jqxChart">
</div>
<script type="text/javascript">
    document.addEventListener('DOMContentLoaded', (event) => {

        var jsonDataWhoisCount = '@Html.Raw(Newtonsoft.Json.JsonConvert.SerializeObject(chartData))';
        var whoisCountAdapterSettings  ={
            datatype: "json",
            datafields: [
                { name: 'Name' },
                { name: 'Share' },
                { name: 'Count' },
                { name: 'From' },
                { name: 'Till' },
            ],
            localdata: jsonDataWhoisCount
        };
        //databind the json using a data adapter
        var dataWhoisCountAdapter = new $.jqx.dataAdapter(whoisCountAdapterSettings, { async: false, autoBind: true, loadError: function (xhr, status, error) { alert('Error loading "' + source.url + '" : ' + error); } });

        //allow for a rendering method of chart the tooltip giving some extra details
        var jqxWhoIsFormatFn = function (value, itemIndex, serie, group, categoryValue, categoryAxis) {
            var dataItem = dataWhoisCountAdapter.records[itemIndex];
            return dataItem.Count + " of @data.Length incidents at " + dataItem.Name + "<br/>Between " + dataItem.From + " and " + dataItem.Till;
        };


        // prepare jqxChart settings
        var settingsdataWhoisCount = {
            title: "ISP's used for malicious activity",
            description: "(Top 10 ISP's are responsible for @chartData.Sum(s=>s.Count) of @data.Length incidents)",
            enableAnimations: true,
            showLegend: false,
            showBorderLine: true,
            legendPosition: { left: 520, top: 140, width: 100, height: 100 },
            padding: { left: 5, top: 5, right: 5, bottom: 5 },
            titlePadding: { left: 0, top: 0, right: 0, bottom: 10 },
            source: dataWhoisCountAdapter,
            colorScheme: 'scheme06',
            seriesGroups:[{
                type: 'pie',
                showLabels: true,
                series:[{
                    toolTipFormatFunction: jqxWhoIsFormatFn,
                    dataField: 'Share',
                    displayText: 'Name',
                    labelRadius: 90,
                    initialAngle: 15,
                    radius: 70,
                    centerOffset: 0
                }]
            }]
        };
        // setup the chart
        $('#jqxWhoisChart').jqxChart(settingsdataWhoisCount);
    });
</script>

The firewall resolves who is accessing the firewall via DNS lookup and WHOIS query. The chart above shows the data centers or internet providers that are hosting the IP addresses used to attack this site..

Penetration attempts

About this sample

The following code is rendered from the partial view used to render the chart URL fishing detected by the firewall.

About the data

All data shown are collected without 3rd party services and use the firewall as model to render the data, you could do this in a API endpoint and have faster page performance however we did this to demonstrate using the firewall as a data source.

The method PhishyVisits of the firewall will query the firewalls data state and returns all PhishyVisitStats that fall in the filtered range. The class property PhishyVisitStats.Whois contains the data of the ISP that was used to access the web application. This sample uses the ISP's Geographical location to render the country name in grid.

The code used to render the chart

The code below uses jqxWidgets for generating the charts, you are able to render the data with any framework you choose.

@inject Walter.Web.FireWall.IFireWall _fireWall
@{
    var data=_fireWall.PhishyVisits(_fireWall.Configuration.Cashing.BufferFirewallData).Where(w => w.StatusCode != System.Net.HttpStatusCode.OK);
    var gridData = data.GroupBy(g=>g.RequestedUrl.PathAndQuery)
                        .Select(s=>new {
                            url = s.Key,
                            count= s.Count(),
                            ip = s.Select(l=>l.CIDR).Distinct().Count(),
                            location=string.Join(", ", s.Where(w=>w.Whois?.Country!= null && w.Whois.Country!= Walter.BOM.Geo.GeoLocation.UnKnown)
                                                        .Select(s=>s.Whois.Country)
                                                        .Distinct()
                                                        .Select(s=>Walter.BOM.Geo.GeoLocationMapping.TryGetCountryName(s,out var name)?name:"un-known"))
                        });


}


<!--Placeholder for the Grid-->
<div id="jqxFishingGrid">
</div>

<script type="text/javascript">
    document.addEventListener('DOMContentLoaded', (event) => {

        var dataFishingGrid = '@Html.Raw(Newtonsoft.Json.JsonConvert.SerializeObject(gridData))';
        var dataFishingAdapterConfig = {
            datatype: "json",
            datafields: [
                { name: 'url', type: 'string' },
                { name: 'count', type: 'number' },
                { name: 'ip', type: 'int' },
                { name: 'location', type: 'string' },
            ],
            pagesize: 20,
            localdata: dataFishingGrid,
            sortcolumn: 'count',
            sortdirection: 'desc'
        };
        var dataFishingAdapter = new $.jqx.dataAdapter(dataFishingAdapterConfig);
        $("#jqxFishingGrid").jqxGrid(
            {
                altrows: true,
                enabletooltips: true,
                editable: true,
                columnsresize: true,
                sortable: true,
                pageable: true,
                width: '100%',
                height:'100%',
                source: dataFishingAdapter,
                columns: [
                    { text: 'Url', datafield: 'url', width: '60%' },
                    { text: "IP's", datafield: 'ip', width: '10%', cellsalign: 'right'},
                    { text: 'Count', datafield: 'count', width: '10%', cellsalign: 'right' },
                    { text: 'Location', datafield: 'location', width: '60%' },

                ]
            });
    });

</script>

The penetration attempt chart shows how often someone tried to extract confidential data or visited a honey-pot page hidden from view from users and search engines. The chart shows the requests against this the web application in the last 30 days. Most BOTS and users stop after we discover them and return a return code >= to 500

URL Fishing

About this sample

The following code is rendered from the partial view used to render the chart URL fishing and code CSP type violations detected by the firewall.

About the data

All data shown are collected without 3rd party services and use the firewall as model to render the data, you could do this in a API endpoint and have faster page performance however we did this to demonstrate using the firewall as a data source.

The method PhishyVisits of the firewall will query the firewalls data state and returns all PhishyVisitStats that fall in the filtered range.

The class property PhishyVisitStats.Whois contains the data of the ISP that was used to access the web application. This sample uses the ISP's Geographical location to render the country name in grid.

The code used to render the chart

The code below uses jqxWidgets for generating the grid, you are able to render the data with any framework you choose.

@using Walter.Web.FireWall.Infrastructure
@inject Walter.Web.FireWall.IFireWall _fireWall
@{
    var data=_fireWall.PhishyVisits(_fireWall.Configuration.Cashing.BufferFirewallData);
    var gridData = data.GroupBy(g=>g.RequestedUrl.AbsolutePath)
                        .Select(s=>new {
                            url = s.Key,
                            count= s.Count(),
                            ip = s.Select(l=>l.CIDR).Distinct().Count(),
                            location=string.Join(", ", s.Where(w=>w.Whois?.Country!= null && w.Whois.Country!= Walter.BOM.Geo.GeoLocation.UnKnown)
                                                        .Select(s=>s.Whois.Country)
                                                        .Distinct()
                                                        .Select(s=>Walter.BOM.Geo.GeoLocationMapping.TryGetCountryName(s,out var name)?name:"un-known"))
                        });


}


<!--Placeholder for the Grid-->
<div id="jqxFishingGrid">
</div>

<script type="text/javascript">
    document.addEventListener('DOMContentLoaded', (event) => {

        var dataFishingGrid = '@Html.Raw(Newtonsoft.Json.JsonConvert.SerializeObject(gridData))';
        var dataFishingAdapterConfig = {
            datatype: "json",
            datafields: [
                { name: 'url', type: 'string' },
                { name: 'count', type: 'number' },
                { name: 'ip', type: 'int' },
                { name: 'location', type: 'string' },
            ],
            pagesize: 20,
            localdata: dataFishingGrid,
            sortcolumn: 'count',
            sortdirection: 'desc'
        };
        var dataFishingAdapter = new $.jqx.dataAdapter(dataFishingAdapterConfig);
        $("#jqxFishingGrid").jqxGrid(
            {
                altrows: true,
                enabletooltips: true,
                editable: true,
                columnsresize: true,
                sortable: true,
                pageable: true,
                width: '100%',
                height:'100%',
                source: dataFishingAdapter,
                columns: [
                    { text: 'Url', datafield: 'url', width: '60%' },
                    { text: "IP's", datafield: 'ip', width: '10%', cellsalign: 'right'},
                    { text: 'Count', datafield: 'count', width: '10%', cellsalign: 'right' },
                    { text: 'Location', datafield: 'location', width: '60%' },

                ]
            });
    });

</script>
The URL fishing grid visualizes the requests made to the application where most of the requests are either honey-pots located in robot-no follow type locations or are known vulnerabilities in .net or other frameworks or plugins.