Scripts

Overview

ACE supports the deployment of any provided scripts uploaded, however currently utilizes PowerShell scripts for Windows hosts and Python scripts for macOS.

Response Format

All ACE scan data must be received by the web server as HTTPS POST with the following data schema regardless of the origin:

{
ComputerName : [string ComputerName],
ScanType : [string ScanType],
RoutingKey : [string RoutingKey],
ResultDate : [date],
ScanId : [string ScanId],
Data : [string[] ScanResults]
}

Description of fields:

• ComputerName - String of the scanned system’s hostname
• ScanType - String for the type of scan performed
• RoutingKey - String representing the enrichment and output. Represented as one or more enrichments separated by a period followed by ‘file’ or ‘siem’
• ScanId - String GUID representing the ScanId
• Data - String array, each entry containing the specific information from the scan

Sample ACE JSON entry:

Any information that is desired can be collected and processed by ACE as long as it can be manipulated into the specified JSON format.

PowerShell Scripts

All ACE scripts should be PowerShell v2 compatible to allow execution on stock Windows 7 systems. For the web server to properly receive the data, it must be formatted as the above JSON and sent to web server via HTTPS POST. Sample code for formatting the proper HTTPS POST is provided below:

function Invoke-AceWebRequest
{
    param
    (
        [Parameter(Mandatory = $true)]
        [string]
        $Uri,

        [Parameter()]
        [string]
        $Body,

        [Parameter()]
        [switch]
        $CheckCert
    )
    Try
    {
        # Create web request
        $WebRequest = [System.Net.WebRequest]::Create($Uri)
    
        $WebRequest.Headers.Add('X-API-Version:1.0')

        $WebRequest.Method = ‘POST’
        $WebRequest.ContentType = ‘application/json’

        if($CheckCert)
        {
            # Set the callback to check for null certificate and thumbprint matching.
            $WebRequest.ServerCertificateValidationCallback = {
        
                $ThumbPrint = 'ServerThumbPrint'
        
                $certificate = [System.Security.Cryptography.X509Certificates.X509Certificate2]$args[1]
                
                if ($certificate -eq $null)
                {
                    $Host.UI.WriteWarningLine("Null certificate.")
                    return $true
                }
        
                if ($certificate.Thumbprint -eq $ThumbPrint)
                {
                    return $true
                }
                else
                {
                    $Host.UI.WriteWarningLine("Thumbprint mismatch. Certificate thumbprint $($certificate.Thumbprint)")
                }
        
                return $false
            }
        }

        if($PSBoundParameters.ContainsKey('Body'))
        {
            $byteArray = [System.Text.Encoding]::UTF8.GetBytes($Body)
            $Webrequest.ContentLength = $byteArray.Length
            
            $dataStream = $Webrequest.GetRequestStream()            
            $dataStream.Write($byteArray, 0, $byteArray.Length)
            $dataStream.Close()
        }

        # Get response stream
        $ResponseStream = $webrequest.GetResponse().GetResponseStream()
    
        # Create a stream reader and read the stream returning the string value.
        $StreamReader = New-Object System.IO.StreamReader -ArgumentList $ResponseStream
        $StreamReader.ReadToEnd()

        $StreamReader.Close()
        $ResponseStream.Close()
    }
    catch
    {
        Write-Error "Failed: $($_.exception.innerexception.message)"
    }
}

Python Scripts

In order to ensure compatibility, ensure that all scripts are Python 2.7 with no dependencies so they can be run on any macOS system. For the web server to properly receive the data, it must be formatted as the above JSON and sent to web server via HTTPS POST. Sample code for formatting the proper HTTPS POST is provided below:

try:
    header = {"content-type": "application/json", "X-API-Version":"1.0"}
    sessioncontext = ssl.SSLContext(ssl.PROTOCOL_SSLv23)
    conn = httplib.HTTPSConnection(host='ACE_Web_Server', context=sessioncontext)
    conn.request('POST', '/scan/uri', dumps(postdata), header)
    response = conn.getresponse()
    data = response.read()
except Exception as e:
    debugbreak()
    cls.log_exception(e)