Threat Detection: Using Cisco’s SecureX with the SecurityTrails Module
Reading time: 14 minutes
Are you a Cisco SecureX user? Conducting cyber threat intelligence campaigns? Now you can integrate the SecurityTrails API™ into your existing SecureX Dashboards, by using a serverless relay running Amazon's Lambda infrastructure.
Cisco SecureX is a cloud-native platform that allows you to connect your infrastructure to create one unified dashboard and increase visibility. This platform allows you to maximize your operational efficiency while reducing threat responsiveness, through a series of available automated workflows.
Using the Cisco SecureX platform in conjunction with the SecurityTrails API™ module will empower your infosec efforts by taking your cyber threat intelligence endeavors to the next level.
- SecurityTrails integration how-to
- Running the tool
- Summary
SecurityTrails integration how-to
Today we're addressing the module's installation and configuration so you can get it ready to go.
The idea behind this setup is to configure a serverless instance using Amazon's Lambda platform. This allows the exchanging of information between our service and Cisco's—without the need to install dedicated infrastructure that adds a fixed additional cost to your OPEX.
Getting the code
First off, you can find all of the code plus the documentation on Cisco Security's Github repository, located here. The complete environment configuration does involve plenty of steps and can be tricky, but we'll do our best to make it as simple and self-explanatory as possible.
To begin configuring, you'll need to clone all the code. Start by running the git clone command, then enter the recently created folder as shown:
$ git clone https://github.com/CiscoSecurity/tr-05-serverless-securitytrails.git
Cloning into 'tr-05-serverless-securitytrails'...
remote: Enumerating objects: 225, done.
remote: Counting objects: 100% (225/225), done.
remote: Compressing objects: 100% (149/149), done.
remote: Total 225 (delta 117), reused 166 (delta 68), pack-reused 0
Receiving objects: 100% (225/225), 57.50 KiB | 525.00 KiB/s, done.
Resolving deltas: 100% (117/117), done.
$ cd tr-05-serverless-securitytrails/
In this folder, you'll find all the necessary files and folders to upload the relay into Lambda.
You must verify the Zappa configuration by checking the zappa_settings.json file included in the cloned folder:
{
"dev": {
"app_function": "app.app",
"aws_region": "us-east-1",
"exclude": [".*", "*.json", "*.md", "*.txt"],
"keep_warm": false,
"log_level": "INFO",
"manage_roles": false,
"profile_name": "serverless",
"project_name": "tr-securitytrails-relay",
"role_name": "tr-serverless-relay-ZappaLambdaExecutionRole",
"runtime": "python3.7",
"s3_bucket": "zappa-tr-securitytrails-relay"
}
}
Amazon Web Services configuration
Configuring AWS can be a difficult task in itself, so we'll explain every step to help you get this relay to work:
- Configure a new user on IAM (Identity and Access Management)
- Retrieve user credentials and place them in your OS's environment for Zappa to use them
- Configure the deployment policy for the serverless user to create the whole environment
- Configure the execution policy for the serverless user to run the relay
Now let's get into specifics.
User setup
Getting this deployment to work properly requires an existing user with a specific role and a set of policies that constrain what this application can and cannot do. This is done by following the steps below:
- Open your AWS console in https://console.aws.amazon.com/
- Choose your desired application region (in this example we'll use US-EAST-1 https://console.aws.amazon.com/console/home?region=us-east-1)
- Enter the IAM by clicking Services > History > IAM located at the top menu to the left of the screen
- Click Access Management > Users located on the left menu
- Click on Add User as shown in the image below
For this deployment, the documentation recommends we set up the user's name to serverless and leave the Programmatic access checkbox on.
Click on the Next: Permissions button followed by Next: Review, and once this is done you're ready to hit the Create user button to finish. As you receive the success message, it's possible you'll get an additional no permissions warning; this is correct and will be solved afterward.
To finalize, you need to download the credentials file as shown above. By clicking on the Download .csv button you'll receive a pair of keys that needs to be placed inside your local configuration files, as stated in the documentation:
"Once the user is created and the credentials are downloaded, the best way to store that data is to put it into your AWS credentials file usually located on ~/.aws/credentials (Linux and Mac) or %USERPROFILE%.aws\credentials (Windows).
Each profile can also specify different AWS regions and output formats in the AWS config file usually located on ~/.aws/config (Linux and Mac) or %USERPROFILE%.aws\config (Windows).".
That's what we did in on our OS, and the files look like this:
- Credentials file (complete this with the values of your downloaded .csv file)
[serverless]
aws_access_key_id=R[...]F
aws_secret_access_key=5[...]p
- Config file (complete this with the profile serverless header and your desired AWS region).
[profile serverless]
region=us-east-1
output=json
For this to work, one important detail is that the profile header name must match the one being configured in the zappa_settings.json file placed inside the recently cloned repository.h The file should look like this:
{
"dev": {
"app_function": "app.app",
"aws_region": "us-east-1",
"exclude": [".*", "*.json", "*.md", "*.txt"],
"keep_warm": false,
"log_level": "INFO",
"manage_roles": false,
"profile_name": "serverless",
"project_name": "tr-securitytrails-relay",
"role_name": "tr-serverless-relay-ZappaLambdaExecutionRole",
"runtime": "python3.7",
"s3_bucket": "zappa-tr-securitytrails-relay.pence"
}
}
Now that the user is covered, we're ready to create a few policies.
Deployment policy
The deployment policy is necessary for our recently created user to run and execute the recipes that automatically create the relay's serverless environment. We'll need to locate the already existing policy file (which includes everything we need to accomplish this) and configure it to match our AWS account as follows.
We'll need to replace the <ACCOUNT_ID> tag inside the ZappaLambdaDeploymentPolicy.json file located in the cloned aws folder.
The ACCOUNT_ID of your AWS account is a 12-digit number that can be found on the Support Center page, at the left of the screen under the Account number. We've placed 555555555555 in the upper left corner of the above picture so you can identify it.
The original policy's .json file looks like this:
{
“Version”: “2012-10-17",
“Statement”: [
{
“Effect”: “Allow”,
“Action”: [
“iam:AttachRolePolicy”,
“iam:GetRole”,
“iam:CreateRole”,
“iam:PassRole”,
“iam:PutRolePolicy”
],
“Resource”: [
“arn:aws:iam::<ACCOUNT_ID>:role/*ZappaLambdaExecutionRole”
]
[…]
And after configuration, it will look like this:
...
"Resource": [
"arn:aws:iam::555555555555:role/*-ZappaLambdaExecutionRole"
]
...
Now, follow these steps to upload the policy:
- Enter the Identity Access Management (IAM) console at AWS
- Select Policies on the left menu
- Click on the Create policy button
- Select the JSON tab and paste the content of the just-configured ZappaLambdaDeploymentPolicy.json file
- Click on the Review policy button
- Name the new policy ZappaLambdaDeploymentPolicy and hit Create policy
Once the creation is finished you'll see the success message, and you can search for the newly created policy in the policies listing:
Now, to attach the policy to the existing serverless user:
- Select Users on your left menu under Access management (you must be at IAM)
- Find the newly created serverless user and click on its name to access configuration
- Click on the Add permissions button
- Select the Attach existing policies directly tab
- Search for the recently created policy named ZappaLambdaDeploymentPolicy
- Tick on the corresponding checkbox and hit the Next: Review button
- Click the Add permissions button
Once this is completed you're ready for the next step: adding the execution policy.
Execution policy
We need to create a policy that gives the user running the Lambda instance access to execute. As with the deployment policy, this is created for you in the ZappaLambdaExecutionPolicy.json file located in the aws folder.
Needed steps are:
- Enter the Identity Access Management (IAM) console at AWS
- Select Policies on the left menu
- Click on the Create policy button
- Select the JSON tab and paste the content of the just configured ZappaLambdaExecutionPolicy.json file
- Click on the Review policy button
- Name the new policy ZappaLambdaExecutionPolicy and hit Create policy
Next, we need to set up roles:
- Under Access management, select the Roles tab
- Select the Create role button
- Select the AWS service tab and choose Lambda, then click on Next: Permissions
- Find the ZappaLambdaExecutionPolicy and enable the corresponding checkbox
- Click the Next: Tags button and then the Next: Review button
- Name the role tr-serverless-relay-ZappaLambdaExecutionRole and click the Create role button
- Find the newly created role and click on its name to access configuration
- Go to the Trust relationships tab and click the Edit trust relationship button
- We need to add apigateway.amazonaws.com to the service field so it looks like the following image:
Now we're ready to deploy!
Deploying your function environment
Once all of these steps are completed, you simply need to execute the Zappa deploy dev command (as shown below) to create the new Lambda environment and get everything ready for posterior use.
$ zappa deploy dev
(Werkzeug 1.0.1 (/Users/me/tr-05-serverless-securitytrails/venv/lib/python3.8/site-packages), Requirement.parse('Werkzeug<1.0'), {'zappa'})
Calling deploy for stage dev..
Downloading and installing dependencies..
- markupsafe==1.1.1: Downloading
100%|██████████████████████████████████| 27.5k/27.5k [00:00<00:00, 1.22MB/s]
- cryptography==3.0: Using locally cached manylinux wheel
- cffi==1.14.2: Using locally cached manylinux wheel
Packaging project as zip.
Uploading tr-securitytrails-relay-dev-1597704684.zip (10.6MiB)..
100%|██████████████████████████████████| 11.1M/11.1M [00:18<00:00, 613kB/s]
Uploading tr-securitytrails-relay-dev-template-1597704715.json (1.6KiB)..
100%|██████████████████████████████████| 1.67k/1.67k [00:00<00:00, 4.81kB/s]
Waiting for stack tr-securitytrails-relay-dev to create (this can take a bit)..
100%|██████████████████████████████████| 4/4 [00:16<00:00, 4.19s/res]
Deploying API Gateway.
Deployment complete!: https://g[...]5.execute-api.us-east-1.amazonaws.com/dev
Post-execution, we need to note the provided AWS URL corresponding to the Lambda instance address that we'll need to configure our Cisco SecureX SecurityTrails module.
SecurityTrails API™ configuration
Curious about how you can get a SecurityTrails API™ key? If you don't already have one (and you definitely should!) the process is extremely simple:
- Go to https://securitytrails.com/app/auth/login and enter your username and password.
- Go to API > API keys at the left menu and click on Create New API Key.
- Fill in the description and hit Create New API Key.
- Enjoy the APIs listed in the API Keys section.
Now we're ready to use our API inside the SecureX module!
Cisco SecureX configuration
Now that we've finished all configurations regarding the AWS and SecurityTrails environment, it's time to set up everything we need on the Cisco SecureX platform. Let's explore account creation and configuration, plus module installation and setup.
Creating a Cisco SecureX account
In case you're not an existing user of this platform you'll need to create a new account. To do so, go to the login page located here, and fill out the create account form. Once completed, you'll receive an email confirmation message to activate your account.
When account activation is complete you'll see a success message.
You can now access your account by accessing the login page here.
Generating the shared secrets
For the lambda function to work, a JSON Web Token (JWT) and a secret key for its validation are needed. To generate these, you need your previously created SecurityTrails API™ Key and a JWT generator tool (you can find a tool to install and use here).
Now to generate the keys, execute the following:
$ jwt dev
Enter: SecurityTrails API™ Key: u[...]7
The JWT for the SecurityTrails module is:
g[...]5.d[...]3.V[...]j
The SECRET_KEY to validate the JWT is:
S[...]x
Use this URL to navigate to the AWS Console and configure the SECRET_KEY environment variable using the above value:
https://console.aws.amazon.com/lambda/home?region=us-east-1#/functions/tr-securitytrails-relay-dev/edit/environment-variables?tab=configuration
Use one of these URLs to navigate to Threat Response in your region and create the SecurityTrails module using your Lambda's URL and the JWT:
US: https://securex.us.security.cisco.com/settings/modules/available/5[...]a/new
EU: https://securex.eu.security.cisco.com/settings/modules/available/2[...]r/new
APJC: https://securex.apjc.security.cisco.com/settings/modules/available/1[...]x/new
Once this step is ready, we're ready to configure the required module with the needed token and Lambda's environment variables.
Configuring the secret key in AWS Lambda
The next step is pretty straightforward: just add a new environment variable inside the already existing Lambda function. The key name should be SECRET_KEY and the corresponding value is the previously created JWT Key.
Once this is done, hit the save button and we're ready to configure the SecurityTrails' module inside Cisco SecureX.
Configuring the SecurityTrails Module inside SecureX
Once inside the SecureX interface you must configure any of the required modules for this to work. In this case, we’ll be showing how to setup and configure the SecurityTrails module.
By looking at the left menu and clicking on the Integrations link, you'll find a list of modules that can be integrated. Check the SecurityTrails module, and click on the Add New Module button.
The module configuration will ask for the module name (unique module instance name), the serverless URL (provided by the Zappa deploy command output), and the authorization bearer (a.k.a. the already generated JWT with the encoded SecurityTrails API™ key).
After the configuration is finished you can check for available integrations on the left side of the dashboard interface.
All necessary steps have been fulfilled at this point. Now we're ready to start using the SecurityTrails module inside Cisco SecureX, by utilizing the AWS Lambda Serverless relay we've configured.
Running the tool
Finally, the last step is to test this integration and enjoy its functionality! To do that, once inside the SecureX interface dashboard, click on Applications > Threat Response > Launch
This will open a new tab with the threat response interface. Here, you can place different objects to check such as IP addresses, domain names, logs, etc.
Now you can see the visible universe of retrieved objects regarding the entered target.
And you can play with different data types and visualizations as well.
You can also be advised about the flow and relationships between objects.
Investigation details can be also seen by clicking on objects to find the source of information.
There's a simpler integration available as well, for pinpointing a particular element in your investigation and extracting all possible data from our free app.
Just click over the target's contextual button, and search for more information with SecurityTrails as shown.
You can expect more integrations and features in the future, so stay tuned for any product updates!
Summary
Today we've covered the integration between the power of SecurityTrails' historic database and Cisco's SecurityX platform. Despite the length of the process and number of parts to be aligned, the ability to integrate both platforms with the use of serverless technology is a major gain in both backend OPEX economy and the combined effectiveness of different APIs and modules with your monitoring dashboard.
