renisac / cif3-pwsh Goto Github PK

PowerShell module wrapper for the Collective Intelligence Framework (CIF) v3 API

License: MIT License

PowerShell 100.00%

powershell cif3 cifv3 cif-instance threat-intelligence threat-sharing powershell-core

cif3-pwsh's Introduction

CIFv3 API PowerShell Wrapper

Collective Intelligence Framework (CIF) is a threat intelligence framework. This project is a CIFv3 client for PowerShell Core and Windows PowerShell.

https://csirtgadgets.com/collective-intelligence-framework

https://github.com/csirtgadgets/bearded-avenger

Getting Started

Install the module:

Install-Module CIF3

Load the module:

Import-Module CIF3

See what functions are available:

Get-Command -Module CIF3

If you have an existing .cif.yml in your $env:HOME dir, its contents will be read and used automatically. If you've never setup your config file (.cif.yml) before, do so now. At a minimum you must set the Uri and Token parameters.

Set-CIF3Config -Uri https://feeds.cif.domain.com -Token aaaabbbbccccdddd

Using the Module

CIF Instance Configuration

Retrieve your CIFv3 config settings:

Get-CIF3Config

Set the URI and authorization token to communicate with the desired CIF instance:

Set-CIF3Config -Uri 'https://cif.domain.local:5000' -Token 'd81830def81a871f2adbf00c5000000'

Test the connection to your configured CIF instance URI (returns $true if working, $false otherwise):

Test-CIF3Auth

Tokens

Tokens in CIF are like API keys, used for authenticating and authorizing a user to perform various actions.

List all tokens on the CIF instance:

Get-CIF3Token

Find a token with username = '[email protected]'

Get-CIF3Token -Name user1@domain.local

Create a new token called 'writeonly' on the CIF instance. It will have write permissions but no read permissions:

New-CIF3Token -Name 'writeonly' -Permission 'Write'

Remove the specified token from the CIF instance:

Remove-CIF3Token -Id 'abcdef9999888855553333'

Update token to be in groups 'everyone' and 'admins':

Set-CIF3TokenGroup -Id 'abcdef9999888855553333' -Group everyone, admins

Indicators

Get a list of all indicators (default ResultSize is 100, so 100 will be returned):

Get-CIF3Indicator

Get up to 500 indicator results that have a Confidence of 8 or greater:

Get-CIF3Indicator -Confidence 8 -ResultSize 500

Get all fqdn indicators reported in the last week that have a 'malware' or 'botnet' tag:

Get-CIF3Indicator -IType fqdn -StartTime (Get-Date).AddDays(-7) -EndTime (Get-Date) -Tag malware, botnet

Add an indicator for 'baddomain.xyz' at a confidence of 7, an amber TLP, and tagged as 'malware'

Add-CIF3Indicator -Indicator baddomain.xyz -Confidence 7 -Tag malware -TLP amber

Search for the indicator 44.227.178.5 and include any matching parent CIDRs that are known. Results are sorted by confidence highest to lowest, with any equal-confidence indicators being further sorted by reporttime oldest to newest before being returned:

Get-CIF3Indicator -Indicator '44.227.178.5' -IncludeRelatives -Sort '-confidence', 'reporttime'

Feeds

Feeds are aggregated, deduplicated, and filtered datasets that have had allowlists applied before being returned. Indicator type is the only mandatory parameter when generating a feed.

Get a feed of all fqdn indicators with a confidence of 7.5 or greater:

Get-CIF3Feed -IType fqdn -Confidence 7.5

Get a feed of all md5 indicators with a confidence of 9 or greater tagged as 'malware.' Additionally, add the ?apiParam=paramValue string to the final REST request:

Get-CIF3Feed -IType md5 -Confidence 9 -Tag 'malware' -ExtraParams @{ 'apiParam' = 'paramValue' }

Acknowledgments

Warren Frame's PSSlack pwsh module for powershell framework ideas.
The official csirtgadgets' CIFv3 Python SDK for reference.

cif3-pwsh's People

Contributors

Stargazers

Watchers

Forkers

geogboe mabaumgartner

cif3-pwsh's Issues

Readme doc

Hi Michael,

Thanks for sharing this module!

In README.md there is an example that has:

Get-CIF3Indicator -Confidence 8 -ResultSet 500

But that returns an error.

Get-CIF3Indicator : A parameter cannot be found that matches parameter name 'ResultSet'.

The parameter ResultSet should be ResultSize instead.

Get-CIF3Indicator -Confidence 8 -ResultSize 500

Linux compatibility issue with Get-CIF3Config

When running the CIF3 module on Linux the API keys are not imported correctly when the module initializes using the Get-CIF3Config function. The client config is functional after using Set-CIF3Config but once the shell is closed, all future imports of the client config do not supply the API keys as specified in .cif.yml.

Steps to Reproduce from a new Linux shell without any CIF3 client config defined:

Import-Module CIF3
Set-CIF3Config -Uri URI -Token Token -ReadToken Token
Confirm correct config with Get-CIF3Config
Close out of shell
Start new shell and import CIF3 module
Get-CIF3Config

The token and read token values now seem to be imported incorrectly.

PS > Get-CIF3Config

Name                           Value
----                           -----
Uri                            https://example.com
ForceVerbose                   False
NoVerifySsl                    True
Token                          ��!
Proxy                          
WriteToken                     
ReadToken                      ��!

This seems to be an issue with the Decrypt function within Get-CIF3Config. It works differently in a non-Windows environment as you might expect.

Request to support Elasticsearch response

When CIF returns an Elasticsearch response, it returns a JSON string and not an object.

Get-CIF3Indicator -Confidence 8 -ResultSize 500

Output:

{"hits":{"hits":[{"_source":{"reporttime":"2020-02-28T04:37:43.000000Z","provider":"0","group":["everyone"],"uuid":"3194dd4d-ff6f-4139-99b4-dce59612df96","tags":["honeypot","dionaea"],"indicator":"0.0.0.0","firsttime":"2020-02-27T00:59:38.000000Z","itype":"ipv4","lasttime":"2020-02-28T04:37:43.000000Z","tlp":"green","count":325,"confidence":8.0,"indicator_ipv4":"0.0.0.0"}},{"_source":{"reporttime":"2020-02-28T04:37:43.473257Z","provider":"0","group":["everyone"],"uuid":"32262f0d-8ff8-4851-8742-50852dcc8b9e","tags":["honeypot","dionaea"],"indicator":"0.0.0.0","firsttime":"2020-02-27T21:54:18.000000Z","itype":"ipv4","lasttime":"2020-02-28T04:37:43.000000Z","tlp":"green","count":0,"confidence":8.0,"indicator_ipv4":"0.0.0.0"}}]}}

I modified an elseif statement in Format-CIF3ApiResponse.ps1 to handle those responses:

        elseif ($Response.message -eq 'success' -or $null -ne $Response.data) {
            Write-Verbose 'Received response from CIF API'
            # Check for Elasticsearch results
            # https://github.com/csirtgadgets/cifsdk-py-v3/blob/a659e84c63ff097942ed8e549340107c66886db6/cifsdk/client/http.py#L121
            if ($InputObject.data -like '{"hits":{"hits":`[{"_source":*') {
                $elasticsearchResult = ConvertFrom-Json -InputObject $InputObject.data
                if ($null -eq $elasticsearchResult.hits.hits._source) {
                    Write-Error -Message "CIF API call succeeded, but responded with incorrect Elasticsearch value: $Response"
                    break
                } else {
                    # set InputObject to hits.hits._sourcedata' property of Invoke-RestMethod return object for further processing
                    $InputObject = $elasticsearchResult.hits.hits._source
                }
            } else {
                # set InputObject to 'data' property of Invoke-RestMethod return object for further processing
                $InputObject = $InputObject.data
            }
        }

Get-CIF3Indicator -Confidence 8 -ResultSize 2