Merge pull request #18 from luhring/same-subnet-int-tests

Total revision of analysis and set logic

Author: luhring

.circleci/config.yml

@@ -5,12 +5,42 @@ version: 2
 jobs:
   build:
     docker:
-      - image: circleci/golang:1.11
+      - image: circleci/golang:1.13.1
+    working_directory: ~/repo
+    steps:
+      - checkout
+      - run: CGO_ENABLED=0 go build -a -o "./build/reach"
 
+  unit_tests:
+    docker:
+      - image: circleci/golang:1.13.1
     working_directory: ~/repo
+    steps:
+      - checkout
+      - run: go test -cover ./reach
 
+  acceptance_tests:
+    docker:
+      - image: circleci/golang:1.13.1
+    working_directory: ~/repo
     steps:
       - checkout
+      - run: curl -sS https://releases.hashicorp.com/terraform/0.12.7/terraform_0.12.7_linux_amd64.zip -o ./terraform.zip && unzip terraform.zip && sudo mv terraform /usr/local/bin/ && which terraform
+      - run: go test -cover ./reach -acceptance -log-tf -test.v
 
-      - run: go build -a -o "./build/reach"
-      - run: go test -v -cover ./...
+workflows:
+  version: 2
+  commit:
+    jobs:
+      - build
+      - unit_tests
+  nightly:
+    triggers:
+      - schedule:
+          cron: "0 0 * * *"
+          filters:
+            branches:
+              only:
+                - master
+    jobs:
+      - acceptance_tests

.data/reach-demo.gif

@@ -1,93 +1,115 @@
 # reach
 
-A tool for examining network reachability issues in AWS.
-
 [![CircleCI](https://circleci.com/gh/luhring/reach.svg?style=svg)](https://circleci.com/gh/luhring/reach)
-[![Go Report Card](https://goreportcard.com/badge/github.com/luhring/reach)](https://goreportcard.com/report/github.com/luhring/reach)
 [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/luhring/reach/blob/master/LICENSE)
 
-**IMPORTANT: THIS IS STILL IN DEVELOPMENT! USE AT YOUR OWN RISK!**
+Reach is a tool for discovering the impact your AWS configuration has on the flow of network traffic.
 
-## Overview
+## Getting Started
 
-reach evaluates the potential for network connectivity between EC2 instances by querying the AWS API for network configuration data.
+To perform an analysis, specify a **source** EC2 instance and a **destination** EC2 instance:
 
-reach determines the ports on an EC2 instance that can be accessed by another EC2 instance, taking into consideration security group rules, instance subnet placements, instance running states, network ACL rules, and route tables.
+```Text
+$ reach <source> <destination>
+```
 
-reach doesn't need to run on any EC2 instance, it just needs to run on a system that has access to the AWS API.
+![Image](.data/reach-demo.gif)
 
-**Disclaimer:** Because reach gets all of its information from the AWS API, reach makes no guarantees about network service accessibility with respect to the operating system or applications running on an EC2 instance. In other words, reach can tell you if your VPC resources and EC2 instances are configured correctly, but reach _can't_ tell you if an OS firewall is blocking network traffic, or if an application listening on a port has crashed.
+Reach uses your AWS configuration to analyze the potential for network connectivity between two EC2 instances in your AWS account. This means **you don't need to install Reach on any servers** — you just need access to the AWS API.
 
-## Uses
+The key benefits of Reach are:
 
-You can ask what ports are reachable on an EC2 instance from the perspective of another instance.
+- **Solve problems faster:** Find missing links in a network path in _seconds_, not hours.
 
-```ShellSession
-$ reach "client instance" "server instance"
-✔ TCP 80
-✔ TCP 443
-```
+- **Don't compromise on security:** Secure your network without worrying about impacting any required network flows.
+
+- **Learn about your network:** Gain better insight into currently allowed network flows, and discover new consequences of your network design.
+
+- **Build better pipelines:** Discover network-level problems before running application integration or end-to-end tests by adding Reach to your CI/CD pipelines.
 
-You can ask about just one specific port.
+## Basic Usage
 
-```ShellSession
-$ reach "web-server" "db-server" --port 1433
-analysis scope: TCP 1433
-not reachable
+The values for `source` and `destination` should each uniquely identify an EC2 instance in your AWS account. You can use an **instance ID** or a **name tag**, and you can enter just the first few characters instead of the entire value, as long as what you've entered matches exactly one EC2 instance.
+
+Some examples:
+
+```Text
+$ reach i-0452993c7efa3a314 i-02b8dfb5537e80860
 ```
 
-You can ask reach to explain its logic for its evaluation:
+```Text
+$ reach i-04 i-02
+```
 
-```ShellSession
-$ reach "web-server" "db-server" --port 1433 --explain
-not reachable
+```Text
+$ reach web-instance database-instance
+```
 
-- The instance "db-server" doesn't have any security groups with an inbound rule that allows access on port TCP 1433.
-- The subnet "database-private-subnet" in which the instance "db-server" resides doesn't have any network ACL rules that allow inbound traffic on port TCP 1433.
+```Text
+$ reach web data
 ```
 
-## CLI Syntax
+**Note:** Right now, Reach can only analyze the path between two EC2 instances when the instances are **in the same subnet**. Adding support for multiple subnets is the top priority and is currently in development.
 
-`reach "first-instance" ["second-instance"] [OPTIONS]`
+## Initial Setup
 
-### Options
+If you've never used Reach before, download the latest version for your platform from the [Releases](https://github.com/luhring/reach/releases) page. (Alternatively, if you've installed the [Go tools](https://golang.org/dl/), you can clone this repository and build from source.)
 
-`--port`, `-p` Restrict analysis to a specified TCP port.
+You need to run Reach from somewhere where you've saved AWS credentials for your AWS account. Reach follows the standard process for locating and using AWS credentials, similar to the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) tool and other AWS-capable tools (e.g. Terraform). If you're not sure how to set up AWS credentials, check out [AWS's documentation for setting up credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html).
 
-`--assert-reachable` Exit non-zero if no traffic is allowed from source to destination (within analysis scope, if specified).
+Once you've set up AWS credentials, you'll need to make sure your IAM user or role has permission to access the necessary resources in your AWS account. Reach only ever needs **read-only** access, it never modifies any resources in your AWS account. Reach makes various requests to the AWS API to describe various network-related resources, such as EC2 instances, VPCs, subnets, security groups, etc.
 
-`--assert-not-reachable` Exit non-zero if any traffic can reach destination from source (within analysis scope, if specified).
+## More Features
 
-`--explain` Explain how the configuration was analyzed.
+### Assertions
 
-### Specifying an instance
+If you deploy infrastructure via CI/CD pipelines, it can be helpful to validate the network design itself before running any tests that rely on a correct network configuration.
 
-reach is able to handle various methods of specifying an EC2 instance.
+You can use assertion flags to ensure that your source **can** or **cannot** reach your destination.
 
-- **By Name tag.** Most people assign a descriptive name to each of their EC2 instances via a "Name" [tag](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html). Example: `"my-database-server"`.
-- **By Instance ID.** This is a reliably unique identifier within the EC2 service, and it's assigned by AWS. Example: `"i-08a43985c56df54e4"`.
+If an assertion succeeds, Reach exits  `0`. If an assertion fails, Reach exits `2`.
 
-#### Notes about instance specification strings
+To confirm that the source **can** reach the destination:
 
-1. **Quotes:** Use quotes to surround instance specification strings as necessary within your shell environment. Quotes never hurt, but sometimes they can be left off -- for example, when using an instance name tag that contains no spaces, only letters and hyphens.
+```Text
+$ reach web-server database-server --assert-reachable
+```
+
+To confirm that the source **cannot** reach the destination:
 
-1. **Shortened strings:** To make CLI text entry less tedious, reach only requires enough of an instance specification string to be unique within the current AWS account and region. For example, let's say you have three EC2 instances in a particular region in your AWS account, and these instances are named "web-01", "web-02", and "db-master". You could refer to the "db-master" instance by typing just `"db"`, since no other instance begins with the same text. This would let you type the command `reach db --inbound`, and reach would understand that you were asking about inbound access to the "db-master" instance. However, it would not be sufficient to use the string `"web"`, since multiple instances have name tags that begin with the text "web". The rules for shortened strings apply to both name tags and instance IDs.
+```Text
+$ reach some-server super-sensitive-server --assert-not-reachable
+```
 
-## Benefits
+### Explanations
 
-**Instant diagnosis.** Instantly pinpoint missing links in a network setup in AWS.
+Normally, Reach's output is very basic. It displays a simple list of zero or more kinds of network traffic that are allowed to flow from the source to the destination. However, the process Reach uses to perform its analysis is more complex.
 
-**Learn about your network.** Gain better insight into currently allowed network flows, and learn how resource configuration affects larger picture.
+If you're troubleshooting a network problem in AWS, it's probably more helpful to see _"why"_ the analysis result is what it is.
 
-**Stay secure.** Tighten security without worrying about impacting any required network flows.
+You can tell Reach to expose the reasoning behind the displayed result by using the `--explain` flag:
+
+```Text
+$ reach web-instance db-instance --explain
+```
 
-**Better deployment pipelines.** Add into CI/CD pipelines alongside infrastructure as code (IaC) deployments to assert business expectations for your network, so you can confirm (or rule out) network-level problems before running integration or end-to-end tests.
+In this case, Reach will provide significantly more detail about the analysis. Specificially, the output will also show you:
 
-## Road map
+- Exactly which "network points" were used in the analysis (not just the EC2 instance, but the EC2 instance's specific network interface, and the specific IP address attached to the network interface)
+- All of the "factors" (relevant aspects of your configuration) Reach used to figure out what traffic is being allowed by specific properties of your resources (e.g. security group rules, instance state, etc.)
 
-- ~~Analyze traffic allowed from one EC2 instance to another, within the same subnet~~
-- Analyze traffic allowed from an EC2 instance in one subnet to an EC2 instance in another subnet, within the same VPC **<-- MVP**
-- Analyze traffic allowed between an EC2 instance and a specified IP address (e.g. user's IP address, specified hostname, etc.)
-- Support for non-EC2 resources within AWS (e.g. ELB, Lambda, gateways, etc.)
-- Support for VPC peering
+## Feature Ideas
+
+- ~~**Same-subnet analysis:** Between two EC2 instances within the same subnet~~ (done!)
+- **Same-VPC analysis:** Between two EC2 instances within the same VPC, including for EC2 instances in separate subnets
+- **IP address analysis:** Between an EC2 instance and a specified IP address that may be outside of AWS entirely (enhancement idea: provide shortcuts for things like the user's own IP address, a specified hostname's resolved IP address, etc.)
+- **Filtered analysis:** Specify a particular kind of network traffic to analyze (e.g. a single TCP port) and return results only for that filter
+- **Other AWS resources:** Analyze other kinds of AWS resources than just EC2 instances (e.g. ELB, Lambda, VPC endpoints, etc.)
+- **Peered VPC analysis**: Between resources from separate but peered VPCs
 - Other things! Your ideas are welcome!
+
+## Disclaimers
+
+- This tool is a work in progress! Use at your own risk, and please submit issues as you encounter bugs or have feature requests.
+
+- Because Reach gets all of its information from the AWS API, Reach makes no guarantees about network service accessibility with respect to the operating system or applications running on a host within the cloud environment. In other words, Reach can tell you if your VPC resources and EC2 instances are configured correctly, but Reach _cannot_ tell you if an OS firewall is blocking network traffic, or if an application listening on a port has crashed.

README.md

@@ -7,23 +7,23 @@ import (
 )
 
 func exitWithError(err error) {
-	fmt.Println(err)
+	_, _ = fmt.Fprintf(os.Stderr, "%v\n", err)
 
 	os.Exit(1)
 }
 
 func exitWithFailedAssertion(text string) {
 	failedMessage := ansi.Color("assertion failed:", "red+b")
 	secondaryMessage := ansi.Color(text, "red")
-	fmt.Printf("%v %v\n", failedMessage, secondaryMessage)
+	_, _ = fmt.Fprintf(os.Stderr, "\n%v %v\n", failedMessage, secondaryMessage)
 
 	os.Exit(2)
 }
 
 func exitWithSuccessfulAssertion(text string) {
 	succeededMessage := ansi.Color("assertion succeeded:", "green+b")
 	secondaryMessage := ansi.Color(text, "green")
-	fmt.Printf("%v %v\n", succeededMessage, secondaryMessage)
+	_, _ = fmt.Fprintf(os.Stderr, "\n%v %v\n", succeededMessage, secondaryMessage)
 
 	os.Exit(0)
 }

cmd/exit.go

@@ -3,18 +3,24 @@ package cmd
 import (
 	"errors"
 	"fmt"
-	"github.com/luhring/reach/reach"
+	"os"
+	"strings"
+
 	"github.com/spf13/cobra"
+
+	"github.com/luhring/reach/reach/analyzer"
+	"github.com/luhring/reach/reach/aws"
+	"github.com/luhring/reach/reach/aws/api"
+	"github.com/luhring/reach/reach/explainer"
 )
 
 const explainFlag = "explain"
-const portFlag = "port"
-const portFlagShorthand = "p"
+const vectorsFlag = "vectors"
 const assertReachableFlag = "assert-reachable"
 const assertNotReachableFlag = "assert-not-reachable"
 
-var shouldExplain bool
-var port uint16
+var explain bool
+var showVectors bool
 var assertReachable bool
 var assertNotReachable bool
 
@@ -35,42 +41,79 @@ See https://github.com/luhring/reach for documentation.`,
 		return nil
 	},
 	Run: func(cmd *cobra.Command, args []string) {
-		awsManager := reach.NewAWSManager()
+		sourceIdentifier := args[0]
+		destinationIdentifier := args[1]
 
-		instanceVector, err := awsManager.CreateInstanceVector(args[0], args[1])
+		var provider aws.ResourceProvider = api.NewResourceProvider()
+
+		source, err := aws.NewSubject(sourceIdentifier, provider)
 		if err != nil {
 			exitWithError(err)
 		}
+		source.SetRoleToSource()
 
-		var filter *reach.TrafficAllowance
-		if port == 0 {
-			filter = nil
-		} else {
-			filter = reach.NewTrafficAllowanceForTCPPort(port)
-			fmt.Printf("analysis scope: TCP %v\n", port)
+		destination, err := aws.NewSubject(destinationIdentifier, provider)
+		if err != nil {
+			exitWithError(err)
+		}
+		destination.SetRoleToDestination()
+
+		if !explain && !showVectors {
+			fmt.Printf("source: %s\ndestination: %s\n\n", source.ID, destination.ID)
+		}
+
+		a := analyzer.New()
+		analysis, err := a.Analyze(source, destination)
+		if err != nil {
+			exitWithError(err)
+		}
+
+		mergedTraffic, err := analysis.MergedTraffic()
+		if err != nil {
+			exitWithError(err)
 		}
 
-		analysis := instanceVector.Analyze(filter)
-		fmt.Print(analysis.Results())
+		if explain {
+			ex := explainer.New(*analysis)
+			fmt.Print(ex.Explain())
+		} else if showVectors {
+			var vectorOutputs []string
+
+			for _, v := range analysis.NetworkVectors {
+				output := ""
+				output += v.String()
 
-		if shouldExplain {
-			fmt.Println("")
-			fmt.Print(analysis.Explanation())
+				vectorOutputs = append(vectorOutputs, output)
+			}
+
+			fmt.Print(strings.Join(vectorOutputs, "\n"))
+		} else {
+			fmt.Print("network traffic allowed from source to destination:" + "\n")
+			fmt.Print(mergedTraffic.ColorStringWithSymbols())
+
+			if len(analysis.NetworkVectors) > 1 {
+				printMergedResultsWarning()
+			}
 		}
 
+		// fmt.Println(analysis.ToJSON()) // for debugging
+
+		const canReach = "source is able to reach destination"
+		const cannotReach = "source is unable to reach destination"
+
 		if assertReachable {
-			if analysis.PassesAssertReachable() {
-				exitWithSuccessfulAssertion("specified traffic flow is allowed")
+			if mergedTraffic.None() {
+				exitWithFailedAssertion(cannotReach)
 			} else {
-				exitWithFailedAssertion("specified traffic flow is not allowed")
+				exitWithSuccessfulAssertion(canReach)
 			}
 		}
 
 		if assertNotReachable {
-			if analysis.PassesAssertNotReachable() {
-				exitWithSuccessfulAssertion("none of specified traffic flow is allowed")
+			if mergedTraffic.None() {
+				exitWithSuccessfulAssertion(cannotReach)
 			} else {
-				exitWithFailedAssertion("some or all of specified traffic flow is allowed")
+				exitWithFailedAssertion(canReach)
 			}
 		}
 	},
@@ -83,8 +126,13 @@ func Execute() {
 }
 
 func init() {
-	rootCmd.Flags().BoolVar(&shouldExplain, explainFlag, false, "explain how the configuration was analyzed")
-	rootCmd.Flags().Uint16VarP(&port, portFlag, portFlagShorthand, 0, "restrict analysis to a specified TCP port")
-	rootCmd.Flags().BoolVar(&assertReachable, assertReachableFlag, false, "exit non-zero if no traffic is allowed from source to destination (within analysis scope, if specified)")
-	rootCmd.Flags().BoolVar(&assertNotReachable, assertNotReachableFlag, false, "exit non-zero if any traffic can reach destination from source (within analysis scope, if specified)")
+	rootCmd.Flags().BoolVar(&explain, explainFlag, false, "explain how the configuration was analyzed")
+	rootCmd.Flags().BoolVar(&showVectors, vectorsFlag, false, "show allowed traffic in terms of network vectors")
+	rootCmd.Flags().BoolVar(&assertReachable, assertReachableFlag, false, "exit non-zero if no traffic is allowed from source to destination")
+	rootCmd.Flags().BoolVar(&assertNotReachable, assertNotReachableFlag, false, "exit non-zero if any traffic can reach destination from source")
+}
+
+func printMergedResultsWarning() {
+	const mergedResultsWarning = "IMPORTANT: Reach detected more than one network path between the source and destination. Reach calls these paths \"network vectors\". The analysis result shown above is the merging of all network vectors' analysis results. The impact that infrastructure configuration has on actual network reachability might vary based on the way hosts are configured to use their network interfaces, and Reach is unable to access any configuration internal to a host. To see the network reachability across individual network vectors, run the command again with '--vectors'.\n\n"
+	_, _ = fmt.Fprint(os.Stderr, "\n"+mergedResultsWarning)
 }