Public/Get-CIF3Feed.ps1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
function Get-CIF3Feed {
    <#
    .SYNOPSIS
        Gets indicator feed from CIF3 API. A feed is a filtered data-set that's been aggregated and had a whitelisted applied.
    .DESCRIPTION
        This cmdlet issues GET to the CIF API /feed endpoint to generate an indicator feed from the CIF instance. Targeted results can be returned by
        specifying parameters.
    .EXAMPLE
        # Get indicator feed with current session token
        PS C:\> Get-CIF3Feed
         
        # Get fqdn feed using a specified token
        PS C:\> Get-CIF3Feed -Token 0000111222333456789abcdef -IType fqdn
 
        # Get feed of high-confidence indicators tagged as 'phishing' using a specified CIF API URI.
        PS C:\> Get-CIF3Feed -Uri http://cif.domain.local -Confidence 8 -Tag phishing -IType fqdn
 
        # Get a very high-confidence feed of 'malware' or 'botnet' tagged ipv4 indicators over the last 24 hours
        PS C:\> Get-CIF3Feed -IType ipv4 -Confidence 9 -Tag malware, botnet -StartTime (Get-Date).AddDays(-1) -EndTime (Get-Date)
 
    .OUTPUTS
        A an array of PSCustomObjects from CIF instance's API composed of indicator properties.
        Properties of each PSCustomObject are itype, cc, timezone, protocol, message, id, city, latitude, longitude, indicator, group, provider, tags,
            description, portlist, confidence, rdata, firsttime, lastttime, reporttime, asn, asn_desc, count, peers, tlp, region, and additional_data
    .PARAMETER Token
        The API token to use when communicating with the CIF API (uses session token if not specified).
    .PARAMETER Uri
        The Base Uri to use for the CIF instance API (uses session Uri if not specified).
    .PARAMETER Indicator
        Indicator value to pass to the API call to narrow down the search server-side.
    .PARAMETER Confidence
        Confidence value to pass to the API call to narrow down the search server-side. Only indicators >= to this value will be returned.
    .PARAMETER Provider
        Provider value to pass to the API call to narrow down the search server-side. Only indicators matching the provider will be returned.
    .PARAMETER Group
        Group value to pass to the API call to narrow down the search server-side. Only indicators matching the group will be returned.
    .PARAMETER Tag
        Tag(s) to pass to the API call to narrow down the search server-side. Only indicators matching the specified tag(s) will be returned.
    .PARAMETER ResultSize
        Limits the max number of results returned by the server to this number. Defaults to 500.
    .PARAMETER IType
        Queries for this specific indicator type (e.g., fqdn, url, ipv4, md5, etc.).
    .PARAMETER StartTime
        Limits matches to those first reported on or after this time. Must be set with EndTime. If not set, server-side only gets last 3 weeks.
    .PARAMETER EndTime
        Limits matches to those first reported on or before this time. Must be set with StartTime. If not set, server-side only gets last 3 weeks.
    .PARAMETER NoLog
        Doesn't log the query on the CIF instance.
    .PARAMETER Raw
        Return the raw response object from the CIF API, versus parsing it and returning custom states/errors.
    .FUNCTIONALITY
        CIF3
    .LINK
        https://github.com/csirtgadgets/bearded-avenger/blob/master/cif/httpd/views/feed/__init__.py
    #>

    [CmdletBinding(DefaultParameterSetName = 'None')]
    param (
        [string]$Token = $Script:CIF3.Token,

        [string]$Uri = $Script:CIF3.Uri,

        [Alias('Q')]
        [string]$Indicator,

        [float]$Confidence,

        [string]$Provider,

        [string]$Group,

        [string[]]$Tag,

        [Alias('Limit')]
        [int]$ResultSize = 500,

        [Parameter(Mandatory = $true)]
        [ValidateSet('ipv4', 'ipv6', 'fqdn', 'url', 'email', 'md5', 'sha1', 'sha256', 'sha512')]
        [string]$IType,

        [Parameter(ParameterSetName = 'ReportTime', Mandatory = $true)]
        [datetime]$StartTime,

        [Parameter(ParameterSetName = 'ReportTime', Mandatory = $true)]
        [datetime]$EndTime,

        [switch]$NoLog,

        [switch]$Raw
    )

    begin {
        $Uri += '/feed'
        
        $Body = @{ }

        # PSBoundParameters contains only params where value was supplied by caller, ie, does not contain
        # default values. The following foreach loop adds all unbound params that have default values
        foreach ($Key in $MyInvocation.MyCommand.Parameters.Keys) {
            $Value = Get-Variable $Key -ValueOnly -ErrorAction SilentlyContinue
            if ($null -ne $Value -and -not $PSBoundParameters.ContainsKey($Key)) { $PSBoundParameters[$Key] = $Value }
        }

        if ($PSBoundParameters.ContainsKey('StartTime')) {
            # try to set datetime object to a string the API will like
            $StrStart = $StartTime.ToString("yyyy-MM-ddT00:00:00Z") # have to set start time HH:mm:ss to 00:00:00 or CIF doesn't like it
            $StrEnd = $EndTime.ToString("yyyy-MM-ddT23:59:59Z") # have to set end time HH:mm:ss to 23:59:59 or CIF isn't happy
            $ReportTime = "$StrStart,$StrEnd"
            $Body.Add('reporttime', $ReportTime) 
        }

        switch($PSBoundParameters.Keys) {
            'NoLog'         { $Body.Add('nolog', $true) }
            'Indicator'     { $Body.Add('q', $Indicator) }
            'Confidence'    { $Body.Add('confidence', $Confidence) }
            'Provider'      { $Body.Add('provider', $Provider) }
            'Group'         { $Body.Add('group', $Group) }
            'Tag'           { $Body.Add('tags', $Tag -join ',') }
            'ResultSize'    { $Body.Add('limit', $ResultSize) }
            'IType'         { $Body.Add('itype', $IType) }
        }
    }

    process {
        Write-Verbose 'Creating request body'

        $Params = @{
            Body    = $Body
            Method  = 'GET'
            Uri     = $Uri
        }

        Write-Verbose 'Adding token to request'
        $Params.Token = $Token
        
        $Response = Send-CIF3Api @Params -ErrorAction Stop
        
        if ($Raw) {
            return $Response
        } 
        else { 
            return Format-CIF3ApiResponse -InputObject $Response 
        }
 
    }
}