Security Engineering Toolkit.
Project description
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.
Documentation
Documentation for this toolkit is provided by Sphinx. As long as docstrings are defined using reST, Sphinx will generate API documentation - including type annotations - directly from modules in this toolkit.
This documentation can be regenerated at any time using make 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 Started
To 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/activate
- Install required development dependencies.
pip install -e .[tests]
Quick Start
The following sections provide examples of how to use Hutch for common use cases - such as querying JupiterOne, or SumoLogic for information.
Datadog
An example of querying Datadog for logs events can be found below:
import getpass
import datetime
from hutch.security import datadog
# 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"',
)
for page in search:
for entry in page.data:
print(entry.attributes)
SumoLogic
An example of querying SumoLogic for all EC2 instances run in the last hour can be found below:
import getpass
from hutch.security import sumologic
# 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.
for messages in sumo.messages(query.id):
for message in messages:
# 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)
JupiterOne
An example of querying JupiterOne for a list of all resources with internet facing sockets can be found below:
import getpass
from hutch.security import jupiterone
# 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 JupiterOne
jone = jupiterone.query.Client("<JUPITERONE_ACCOUNT>", getpass.getpass())
# Perform queries for all resources, and store for processing.
for query in queries:
search = jone.perform(query)
# Page over results printing all known and extracted information about internet
# facing socket listeners.
for page in search:
for resource in page.results:
print(resource.properties)
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.