Use Cases: Log Ip's for all the members of a group/team. While chrome is running it will log the users IP every 30 minutes. Useful for creating IP white/blacklists for metrics, security purposes, etc.
- A client-side browser extension built using React, for chrome.
- User configurable webhook allows logging IP to specified API endpoint.
- Tag IP addresses with user defined key/value pairs, useful for filtering & sorting IP data.
- Serverless architecture uses API Gateway, Lambda, CloudFront CDN, DynamoDB.
- Easily Deployed using CloudFormation scripts to your AWS account.
- Minimize costs by avoiding paying for compute, virtual machines, or containers.
- Nodejs to compile your browser extension. (Installed with v14.x)
- An AWS Account
- A domain name controlled by a hosted zone in AWS Route53
- CloudFormation: Deployment Scripts for your AWS architecture
- extension: The client-side web application used to log IPs.
- ipmanagementPage: A simple static site for reviewing logged ips
- lambda: Source code for backend APIs.
- img: images used in this guide.
Additional implementation details available in subfolder Readme.md files.
Required Node Package Manager(NPM)
- Run the following commands from the CLI:
> cd /extension
> npm install
> npm run build
- In chrome, navigate to: chrome://extensions/
- Click "Load Unpacked."
- Navigate to ./extension/dist and click "select folder"
- Verify that installation was successful:
- Consider pinning the extension while verifying setup:
- Open the extension and set webhook and username/email. Note that provided CloudFormation template will deploy login API endpoint to yourdomain.com/api/logip
- Add any additional IP key/value pair tags by using the "New Query Parameter" option
- Click Log IP to verify setup. (Backend Setup needs to be complete for this to work)
Backend services can be setup using the AWS console. This guide assumes you have already purchased a domain name and it's part of an AWS route53 hosted zone. CloudFormation will require an IAM role with necessary permissions to deploy the backend CloudFormation stacks. If you do not already have a CloudFormation role setup navigate to IAM in the AWS console and create a role with the trust relationship shown below. Attach "AdministratorAccess" permission to the role.
It's recommended that you create your stacks in us-east-1.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "Cloudformation.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
With your CloudFormation role created and your domain added to your AWS Route53 hosted zone:
- Login to AWS console and navigate to route53, click hosted zones, and select the desired hosted zone name hyperlink.
- Click "hosted zone details" and take note of the "hosted zone Id". You will need it while setting up CloudFormation stacks.
- Navigate to "CloudFormation" in the AWS. This applications cloud formation stacks should be able to be deployed to most regions. However, the A-Record for the stack management page needs to be hosted in us-east-1 to meet CloudFormation requirements. Make sure your current region is us-east-1
- Click "create stack" & select "with new resource".
- Click "template is ready" -> upload a template file -> choose file -> navigate to ./CloudFormation and select "ipManagment.us-east-1.yml" then click next.
- Setup your stack details. See instructions shown below. Fill everything out then hit next.
- Select the role you configured for CloudFormation then click next.
-
Review your setup then click "Submit".
-
You should be taken to your new stacks "events" screen. Wait for the create of your stack to reach the complete stage:
- If you have a desired deployment region, you can now switch to that region ex. "us-west-1". It is recommended that your deploy to us-east-1.
Repeat the above steps above for the remaining CloudFormation templates in the order shown below. Stack parameter values shown as bullet points and used in step 6
- dynamodb.yml: Creates a dynamoDB table used to store logged IP data.
- readCapacityUnits: 5 <-- minimum amount, increase as needed.
- writeCapacityUnits: 10 <-- minimum amount, increase as needed.
- lambda.yml: Creates Lambda Functions that retrieve and store IPs in dynamo
- apiGateway.yml: Creates API endpoints that interact with Lambdas
- HostedZoneId: alpha numeric string noted in step 2.
- ipmanagementpage.yml: Deploys a simple static webpage for reviewing stored IPs.
- customDomainName: yourdomain.com <-- update yourdomain
- HostedZoneId: string noted in step 2.
- CertficateARN: Amazon Resource Name(ARN) for certificate created in step 1. Go to us-east-1, Certficate manager, select your certficate, and copy the ARN.
- username: site username
- password: site password
After all stack deployments are complete you need to compile your static site and upload it to the s3.
> cd ./ipmanagementpage
> npm install
> npm run build
Navigate to s3 in the AWS console. Find the CloudFormation bucket for your site. Click the bucket name, click upload, and upload both the files and folders from ./ipmanagementpage/build.
If your primary domain is already in use the CloudFormation scripts will allow you to use a subdomain for your backend services. Instead of using yourdomain.com you could use ip.yourdomain.com
Your static management page is deployed using the global Content Delivery Network(CDN) CloudFront. CloudFront will cache old versions of your site for up to 24 hours. If you make an update to your management site and want to immediately see the changes you can create an invalidation in CloudFront or add a query paramater to your domain name ex. yourdomain.com?1=1
Use curl to verify that your API endpoints are working correctly
curl -v -X GET https://yourdomain.com/api/getips
curl -v -X POST -H "Content-Type: application/json" -d '{"ip":"9.9.9.9", "userid":"testuser","date":"1999-12-31"}' https://yourdomain.com/api/logip
If your static site returns a "403: Not authorized" error changes are you forgot to upload your static site to s3.
Chrome extension documentation is available at: https://developer.chrome.com/docs/extensions/. WIth a Chrome Developer Account you can publish your own extension build and share it with your team. Warning, it can take some time for your app to get approved.