Mapping an AWS Account Using Faddom

Faddom can monitor traffic on your Amazon AWS environment. To do so, you will need to select the VPCs you wish to discover.

Before connecting Faddom to your AWS account, make sure the following are in place:

Giving Faddom access to your AWS environment has two parts:

Option A: IAM User with Access Keys

Create an IAM user and attach the policies from Permissions to it. Once the IAM user is created, generate an Access Key and Secret Key for it (see AWS Account and Access Keys). You'll enter these credentials directly into Faddom.

Option B: Assign the Role to the Faddom VM or Proxy (Default Credentials)

If Faddom, or the Faddom proxy, is deployed on AWS, you can instead attach the IAM role carrying the policies from Permissions directly to that EC2 instance, rather than creating a separate IAM user. In Faddom, select Default Credentials. Faddom will then automatically use the role and credentials already assigned to the instance, with no access key or secret key required.
​
​Note: Option B is applicable only if the Faddom server or the Faddom proxy has been deployed on AWS. For on-prem deployments of Faddom, please proceed with Option A.

1. If you're using Option A, enter the access key for the IAM user in the credentials field. If you're using Option B (Default Credentials), select Use AWS Default Provider Chain.

2. Click SET CREDENTIALS.

For large environments, you can route AWS discovery through a Faddom proxy server. This helps balance the processing load and reduce bandwidth between the Faddom server and your AWS environment.

To enable this, check Need proxy in the AWS discovery configuration screen and select the relevant proxy.

A Faddom proxy can also be deployed in your AWS environment itself. For more information, see our guide on Deploying the Faddom Proxy in the Cloud.

If you wish to add multiple accounts, you can either add the credentials each time by repeating the steps above, or (if you are using an AWS Organization with multiple accounts) set up Cross-Account Role Assumption once, so you don't need to enter credentials for every account individually. See Cross-Account Role Setup for the full walkthrough of creating the role and trust policy. Once that's set up, check the Cross Account Access selection box when entering credentials for the Origin Account.

Here you will be presented with a list of your AWS Accounts. Select the ones that you would like Faddom to discover.

Here you will select the regions, service types, and VPCs that you would like Faddom to discover.

Next, you'll be prompted to configure how Faddom reads VPC Flow Logs for the selected account. This requires Flow Logs to already be set up in AWS (see Setting Up VPC Flow Logs for the prerequisites and permissions).

Choose one of the following options:

Click APPLY FLOW LOGS SETTINGS to save.

Once discovery completes, discovered objects appear in Maps as their own tiers and in Inventory. Selecting an object opens a side panel showing its relevant key values, using the same layout as a regular server.

Discovered cloud services (Lambda functions, API Gateway, S3 buckets, SQS, SNS, and Secrets Manager) appear on the Application Map as their own tiers, alongside standard EC2, ECS, and RDS objects.

Once VPC Flow Logs are enabled, Faddom maps dependencies between your EC2 instances, the same way it maps on-prem servers using NetFlow or sFlow.

Once X-Ray and Application Signals are enabled, traced dependencies between API Gateway and Lambda are also drawn as connections on the map.

Faddom can use the VPC Flow Logs feature of AWS to map dependencies between your EC2 instances — the AWS equivalent of enabling NetFlow or sFlow collection for on-prem environments. To read the flow logs, they need to be published to an S3 bucket to which Faddom has access using the VPC Flow Logs Permissions. You need to use the AWS Default Format and ensure the log files are in text format. Both daily and hourly S3 path partitioning are supported.

For further information, see the AWS documentation:

If you have multiple accounts, you can set up the flow logs to be stored in a single S3 bucket on one of the accounts. This can then be set up on Faddom to read all the flow logs stored in the S3 bucket. In this case, Faddom only requires the credentials of the account hosting the S3 bucket.

To enable cloud services discovery using Application Signals, the following must be configured in your AWS environment in addition to the Cloud Services Discovery Permissions below.

To enable X-Ray active tracing on your API Gateway stage, follow the official AWS API Gateway X-Ray Setup Guide.

Step 1. Navigate to Application Signals: Open the CloudWatch Console, then go to Application Signals > Services.

Step 2. Enable Application Signals: Click Enable CloudWatch Application Signals.

Step 3. Select Lambda Functions: Select Lambda from the list of target services, then choose the specific Lambda functions you want to monitor.

Step 4. Review Auto-Instrumentation: This process automatically attaches an OpenTelemetry (OTel) layer to your selected Lambda functions to capture telemetry data.

Important note for versioned Lambdas: By default, Application Signals auto-instruments the $LATEST published version of your Lambda function. If your application uses published Lambda versions or aliases, attaching the OTel layer to $LATEST will not automatically update your deployed versions. You must publish a new Lambda version after the layer is added so that Faddom can successfully collect trace data.

You can use the following JSON policy, which contains the minimum required permissions to define the IAM policy for the user:

For help creating IAM users, see the AWS documentation here. For help creating IAM policies from JSON files, see the AWS documentation here.

The following additional permissions are optional and should be added to the above policy only if you would like to give Faddom permission to collect the free disk space of your instances:

To actually collect this data, you also need to install the AWS SSM agent on each server you wish to have data for. For instructions on installing the agent, please follow the AWS guide Working with SSM Agent.

In addition to standard EC2, ECS, and RDS discovery, Faddom can discover and map the following AWS PaaS/serverless object types:

The following JSON policy contains the necessary permissions to discover cloud services:

Enabling discovery of API Gateway and Lambda via Application Signals also requires additional setup — see Setting Up X-Ray and Application Signals.

To read VPC Flow Logs, they need to be published to an S3 bucket to which Faddom has access. The permissions needed are s3:ListBucket and s3:GetObject:

Note: replace [FLOW_LOGS_BUCKET] with the bucket name where flow logs are stored.

If you're using Cross Account Access to map multiple accounts under an AWS Organization, set up the role as follows:

Step 1. Choose an Origin Account. This has to be a management account, or a member account that is a delegated administrator. This is the account whose credentials will be added to Faddom and will have access to the Target Accounts.

Step 2. Create an IAM user in the Origin Account with the standard Permissions that Faddom requires to enable discovery.

Step 3. In the Origin Account, add the below permission:

Step 4. Create a policy in the Origin Account to allow assuming the role, and attach it to the user that will be used in Faddom:

Step 5. In each Target Account, create a role called FaddomCrossAccountUser and attach the below custom trust policy to it:

Step 6. Attach the standard IAM permissions that Faddom requires to the FaddomCrossAccountUser role in each Target Account to allow discovery.

Once this is set up, go back to Entering Credentials in Faddom and check the Cross Account Access box for the Origin Account's credentials.