{"id":13821261,"url":"https://github.com/trulia/cidr-house-rules","last_synced_at":"2025-07-31T22:36:26.870Z","repository":{"id":26932836,"uuid":"108915250","full_name":"trulia/cidr-house-rules","owner":"trulia","description":"An API and collection system to centralize important AWS resource information across multiple accounts","archived":false,"fork":false,"pushed_at":"2020-07-16T16:12:14.000Z","size":10107,"stargazers_count":86,"open_issues_count":0,"forks_count":6,"subscribers_count":15,"default_branch":"master","last_synced_at":"2024-11-19T21:36:00.520Z","etag":null,"topics":["aws","aws-apigateway","aws-dynamodb","aws-lambda","privatelink","python","serverless","serverless-framework","source-of-truth"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trulia.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-10-30T22:26:25.000Z","updated_at":"2024-09-01T18:45:32.000Z","dependencies_parsed_at":"2022-08-27T17:20:13.435Z","dependency_job_id":null,"html_url":"https://github.com/trulia/cidr-house-rules","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trulia%2Fcidr-house-rules","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trulia%2Fcidr-house-rules/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trulia%2Fcidr-house-rules/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trulia%2Fcidr-house-rules/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trulia","download_url":"https://codeload.github.com/trulia/cidr-house-rules/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254530640,"owners_count":22086651,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-apigateway","aws-dynamodb","aws-lambda","privatelink","python","serverless","serverless-framework","source-of-truth"],"created_at":"2024-08-04T08:01:18.836Z","updated_at":"2025-05-16T12:33:03.511Z","avatar_url":"https://github.com/trulia.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# cidr-house-rules\n[![Build Status](https://travis-ci.org/trulia/cidr-house-rules.svg)](https://travis-ci.org/trulia/cidr-house-rules)\n\nA lightweight API and collection system to centralize important AWS resource information across multiple accounts in near-realtime\n\n![cidr-house-rules](https://user-images.githubusercontent.com/538171/37231223-3ee8eda2-239f-11e8-8ca6-6cb58da11d48.png)\n\n#### Collection subsystem\n\nCentralized AWS Lambda functions assume role on monitored AWS accounts to collect the following:\n\n* [NAT Gateway IPs](https://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/vpc-nat-gateway.html) with associated VPCs and environment tags\n* [EIPs](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html)\n* [VPC CIDR blocks](https://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/working-with-vpcs.html) (including associated CIDR blocks)\n* [Classic ELBs](http://docs.aws.amazon.com/elasticloadbalancing/latest/classic/introduction.html)\n* [ALBs, NLBs (elbv2)](https://aws.amazon.com/documentation/elastic-load-balancing/)\n* Available IPv4 Addresses per subnet (Note that the IPv4 addresses for any stopped instances are considered unavailable)\n\nItems collected into Dynamodb will expire if no longer found (default is 48 hours). TTLs are controlled via environment variables passed to each import function. TTL time is expressed in seconds. It is a calculation of current time + TTL. Each import related DynamoDB table leverages [TTL](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/TTL.html) for object expiration\n\n##### Collection subsystem runner process\n\nThe above noted cidr-house-rules collection functions are triggered by a [runner function](https://github.com/trulia/cidr-house-rules/blob/master/runner.py) which invokes the necessary number of\nimport functions based upon the number of AWS accounts managed and number of regions provided by AWS. The runner process allows for cidr-house-rules to scale given any number of AWS accounts to collect information from.\n\n###### Import functions invokation visual\n\n![import-function-invoke](https://user-images.githubusercontent.com/538171/37374885-71c37074-26da-11e8-9531-182c228088a9.png)\n\n#### API interface\n\nAn API interface is provided to expose collected data for consumption. Example usage is through Terraform's [http data source](https://www.terraform.io/docs/providers/http/data_source.html)\n\n* retrieve all NAT Gateways for a given AWS account (team)\n* retrieve all EIPs for a given AWS account (team)\n* lookup a given CIDR block, i.e. 10.0.16.0/16 for potential VPC peering conflicts\n\n#### Terraform modules that use cidr-house-rules for dynamic data\n\n* [Dynamic NAT Gateway Security Group Terraform Module](https://github.com/trulia/cidr-house-rules-terraform-nat-gateway-sg)\n\n#### Deployment\n\n1. Requires [serverless-aws-documentation plugin](https://www.npmjs.com/package/serverless-aws-documentation)\n2. Pick an AWS account to deploy cidr-house-rules to.\n3. On remote accounts applying the supporting terraform see link below to generate role access\n4. With roles generated on remote accounts you can now move serverless.yml.example to serverless.yml and add your target account roles\n5. Run ```serverless deploy --stage prod```\n\n#### Onboarding new AWS accounts\n\n1. Apply the following Terraform and obtain outputs\n\n```hcl\nprovider \"aws\" {\n  region = \"us-west-2\"\n}\n\nmodule \"cidr-house-rules-role\" {\n  cidr_house_rules_account_number = \"123456770\"\n  serverless_stage                = \"prod\"\n  serverless_region               = \"us-west-2\"\n  source                          = \"git::ssh://git@github.com/trulia/cidr-house-rules-role.git?ref=v0.0.1\"\n}\n\noutput \"account_alias\" {\n  value = \"${module.cidr-house-rules-role.account_alias}\"\n}\n\noutput \"account_id\" {\n  value = \"${module.cidr-house-rules-role.account_id}\"\n}\n\noutput \"cidr-house-rules-role\" {\n  value = \"${module.cidr-house-rules-role.cidr-house-rules-role}\"\n}\n```\n\n2. With the account_alias, account_id to app\n\n```bash\ncurl \\\n  --header \"X-Api-Key: \u003cGET_KEY_FROM_AWS_API_GATEWAY\u003e\" \\\n  https://yourapigateway-endpoint-generated-by-serverless.com/prod/add_account?team=trucomms?account=35682931234\n```\n\n3. Add the role for Lambda functions to use in serverless.yml\n\n```\nUnder this section add the new role, there should be a list of them already\niamRoleStatements:\n  - Effect: Allow\n    Action: sts:AssumeRole\n    Resource:\n      arn:aws:iam::\u003cremote_aws_account_number_here\u003e:role/role_cidr_house\n```\n\n4. Run deployment job in Jenkins noted in the \"Deployment\" section\n\n\n#### Example API calls\n\n##### Obtain NAT gateways for platform, webteam and dataeng teams\n\n```bash\ncurl \\\n  --header \"X-Api-Key: \u003cGET_KEY_FROM_AWS_API_GATEWAY\u003e\" \\\n   https://yourapigateway-endpoint-generated-by-serverless.com/prod/get_nat_gateways_for_team?platform\u0026webteam\u0026dataeng\n\n# Or just one team\ncurl \\\n  --header \"X-Api-Key: \u003cGET_KEY_FROM_AWS_API_GATEWAY\u003e\" \\\n  https://yourapigateway-endpoint-generated-by-serverless.com/prod/get_nat_gateways_for_team?team=platform\n```\n\n##### Obtain NAT gateways for all monitored accounts\n\n```bash\ncurl \\\n  --header \"X-Api-Key: \u003cGET_KEY_FROM_AWS_API_GATEWAY\u003e\" \\\n   https://yourapigateway-endpoint-generated-by-serverless.com/prod/get_nat_gateways_for_all\n```\n\n##### Obtain number of result pages for NAT gatways, useful for Terraform to count out resources on\n\n```bash\n# Default is 50 results per page\ncurl --header \"X-Api-Key: \u003cGET_KEY_FROM_AWS_API_GATEWAY\u003e\" 'https://yourapigateway-endpoint-generated-by-serverless.com/prod/get_number_of_nat_gateway_pages'\n```\n\n```bash\n# Request number of results per page to be 10, and return total number of pages\ncurl --header \"X-Api-Key: \u003cGET_KEY_FROM_AWS_API_GATEWAY\u003e\" 'https://yourapigateway-endpoint-generated-by-serverless.com/prod/get_number_of_nat_gateway_pages?results_per_page=10'\n```\n\n##### Obtain paged results of Nat gateways results\n\n```bash\ncurl --header \"X-Api-Key: \u003cGET_KEY_FROM_AWS_API_GATEWAY\u003e\" 'https://yourapigateway-endpoint-generated-by-serverless.com/prod/get_nat_gateways_for_all?results_per_page=10\u0026page=4'\n```\n\n##### Check for a VPC CIDR conflict\n\n```bash\ncurl \\\n  --header \"X-Api-Key: \u003cGET_KEY_FROM_AWS_API_GATEWAY\u003e\" \\\n  https://yourapigateway-endpoint-generated-by-serverless.com/dev/check_conflict?cidr=10.17.0.0/16\n```\n\n##### Obtain all ELBs, ALBs, NLBs across all accounts\n\n```bash\ncurl \\\n--header \"X-Api-Key: \u003cGET_KEY_FROM_AWS_API_GATEWAY\u003e\" \\\nhttps://yourapigateway-endpoint-generated-by-serverless.com/dev/get_elbs_for_all\n```\n\n##### Obtain all PrivateLink endpoint services across all accounts\n\n```bash\ncurl \\\n--header \"X-Api-Key: \u003cGET_KEY_FROM_AWS_API_GATEWAY\u003e\" \\\nhttps://yourapigateway-endpoint-generated-by-serverless.com/dev/get_service_endpoints_for_all\n```\n\n##### Obtain a specific PrivateLink endpoint service based upon the \"Name\" tag of an NLB associated with it. (AWS presently doesn't allow tagging of PrivateLink endpoint services, so next best option is to use tags of NLB associated with PrivateLink)\n\n```bash\ncurl \\\n--header \"X-Api-Key: \u003cGET_KEY_FROM_AWS_API_GATEWAY\u003e\" \\\nhttps://yourapigateway-endpoint-generated-by-serverless.com/dev/get_service_endpoints_for_nlb?nlb=my-nlb\n```\n\n##### Add a new account\n\n```bash\ncurl \\\n  --header \"X-Api-Key: \u003cGET_KEY_FROM_AWS_API_GATEWAY\u003e\" \\\n  https://yourapigateway-endpoint-generated-by-serverless.com/dev/add_account?team=my_aws_account_alias_here\u0026account=35682931234\n```\n\n#####  Supporting Terraform\n\n[cird-house-rules-role](https://github.com/trulia/cidr-house-rules-role) - use this Terraform on your accounts you would like your cidr-house-rules deployment to have access to. The outputs on this Terraform can then be used in your serverless.yml. The account number of the remote account can then be added using the `add_account` API endpoint.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrulia%2Fcidr-house-rules","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrulia%2Fcidr-house-rules","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrulia%2Fcidr-house-rules/lists"}