Package: hutch-security
Hutch - Security Engineering Toolkit.This toolkit provides a collection of widgets commonly used by the HashiCorp Security
Engineering team.Why Hutch? Hutch provides a home for smaller tools which aren't large enough for a home
of their own.DocumentationDocumentation for this toolkit is provided by Sphinx. As long as docstrings are defined
usingreST, Sphinx will generate API
documentation - including type annotations - directly from modules in this toolkit.This documentation can be regenerated at any time usingmake documentation.Please ensure to push code changes and documentation updates as separate commits to
enable reviewers to more easily identify relevant code changes during review.Getting StartedTo begin developing a new module in this toolkit the following steps should be followed:Clone the repository to your workstation.Create a new virtual environment for use during development.python3 -m venv env
source env/bin/activateInstall required development dependencies.pip install -e .[tests]Quick StartThe following sections provide examples of how to use Hutch for common use cases - such
as querying JupiterOne, or SumoLogic for information.DatadogAn example of querying Datadog for logs events can be found below:importgetpassimportdatetimefromhutch.securityimportdatadog# Setup the client.client=datadog.events.Client(api_key=getpass.getpass("Datadog API Key: "),app_key=getpass.getpass("Datadog App Key: "),)now=datetime.datetime.now(tz=datetime.timezone.utc)# Define the datetime objects for the wanted search window.# Perform the query against Datadog. This returns a generator which returns all results# while handling pagination for you.search=client.search(start=now-datetime.timedelta(hours=1),end=now,query=f'@request.source_ip:"192.0.2.1"',)forpageinsearch:forentryinpage.data:print(entry.attributes)SumoLogicAn example of querying SumoLogic for all EC2 instances run in the last hour can be
found below:importgetpassfromhutch.securityimportsumologic# Setup the client / authentiate with Sumo.sumo=sumologic.search.Client("<SUMO_CLIENT_ID>",getpass.getpass())now=datetime.datetime.now(tz=datetime.timezone.utc)# Perform the query against SumoLogic. This returns a job identifier, which must be used# when querying for results.query=sumo.query(f'_sourceCategory=aws/cloudtrail/o-* "RunInstances"',start=now-datetime.timedelta(hours=1),end=now,)# As this is a non-aggregated query, we use `sumo.messages` to get the raw messages. If# this was an aggregation, we'd need to use `sumo.records` instead.formessagesinsumo.messages(query.id):formessageinmessages:# Print the user (`src_user` who executed the "RunInstances" operation. This# field is extracted using an FER in SumoLogic, which is automatically mapped# to the Python object by Hutch.print(message.src_user)JupiterOneAn example of querying JupiterOne for a list of all resources with internet facing
sockets can be found below:importgetpassfromhutch.securityimportjupiterone# Use the Hutch provided "canned" queries for internet facing socket listeners.queries=[jupiterone.queries.INTERNET_LISTENERS_GCP_COMPUTE,jupiterone.queries.INTERNET_LISTENERS_AWS_EC2,jupiterone.queries.INTERNET_LISTENERS_AZURE_VM,jupiterone.queries.INTERNET_LISTENERS_AWS_ALB,jupiterone.queries.INTERNET_LISTENERS_AWS_ELB,jupiterone.queries.INTERNET_LISTENERS_AWS_NLB,jupiterone.queries.INTERNET_LISTENERS_AZURE_LB,]# Setup the client / authenticate with JupiterOnejone=jupiterone.query.Client("<JUPITERONE_ACCOUNT>",getpass.getpass())# Perform queries for all resources, and store for processing.forqueryinqueries:search=jone.perform(query)# Page over results printing all known and extracted information about internet# facing socket listeners.forpageinsearch:forresourceinpage.results:print(resource.properties)