Added more API documentation

internal/scan.go

@@ -19,94 +19,31 @@ type ScannedResult struct {
 	Timestamp time.Time `json:"timestamp"`
 }
 
-func rawConnect(host string, ports []int, timeout int, keepOpenOnly bool) []ScannedResult {
-	results := []ScannedResult{}
-	for _, p := range ports {
-		result := ScannedResult{
-			Host:      host,
-			Port:      p,
-			Protocol:  "tcp",
-			State:     false,
-			Timestamp: time.Now(),
-		}
-		t := time.Second * time.Duration(timeout)
-		port := fmt.Sprint(p)
-		conn, err := net.DialTimeout("tcp", net.JoinHostPort(host, port), t)
-		if err != nil {
-			result.State = false
-			// fmt.Println("Connecting error:", err)
-		}
-		if conn != nil {
-			result.State = true
-			defer conn.Close()
-			// fmt.Println("Opened", net.JoinHostPort(host, port))
-		}
-		if keepOpenOnly {
-			if result.State {
-				results = append(results, result)
-			}
-		} else {
-			results = append(results, result)
-		}
-	}
-
-	return results
-}
-
-func GenerateHosts(subnet string, subnetMask *net.IP) []string {
-	if subnet == "" || subnetMask == nil {
-		return nil
-	}
-
-	// convert subnets from string to net.IP
-	subnetIp := net.ParseIP(subnet)
-	if subnetIp == nil {
-		// try parse CIDR instead
-		ip, network, err := net.ParseCIDR(subnet)
-		if err != nil {
-			return nil
-		}
-		subnetIp = ip
-		if network != nil {
-			t := net.IP(network.Mask)
-			subnetMask = &t
-		}
-	}
-
-	mask := net.IPMask(subnetMask.To4())
-
-	// if no subnet mask, use a default 24-bit mask (for now)
-	return generateHosts(&subnetIp, &mask)
-}
-
-func generateHosts(ip *net.IP, mask *net.IPMask) []string {
-	// get all IP addresses in network
-	ones, _ := mask.Size()
-	hosts := []string{}
-	end := int(math.Pow(2, float64((32-ones)))) - 1
-	for i := 0; i < end; i++ {
-		// ip[3] = byte(i)
-		ip = util.GetNextIP(ip, 1)
-		if ip == nil {
-			continue
-		}
-		// host := fmt.Sprintf("%v.%v.%v.%v", (*ip)[0], (*ip)[1], (*ip)[2], (*ip)[3])
-		// fmt.Printf("host: %v\n", ip.String())
-		hosts = append(hosts, ip.String())
-	}
-	return hosts
-}
-
-func ScanForAssets(hosts []string, ports []int, threads int, timeout int, disableProbing bool, verbose bool) []ScannedResult {
+// ScanForAssets() performs a net scan on a network to find available services
+// running. The function expects a list of hosts and ports to make requests.
+// Note that each all ports will be used per host.
+//
+// This function runs in a goroutine with the "concurrency" flag setting the
+// number of concurrent requests. Only one request is made to each BMC node
+// at a time, but setting a value greater than 1 with enable the requests
+// to be made concurrently.
+//
+// If the "disableProbing" flag is set, then the function will skip the extra
+// HTTP request made to check if the response was from a Redfish service.
+// Otherwise, not receiving a 200 OK response code from the HTTP request will
+// remove the service from being stored in the list of scanned results.
+//
+// Returns a list of scanned results to be stored in cache (but isn't doing here).
+func ScanForAssets(hosts []string, ports []int, concurrency int, timeout int, disableProbing bool, verbose bool) []ScannedResult {
 	var (
 		results  = make([]ScannedResult, 0, len(hosts))
-		done     = make(chan struct{}, threads+1)
-		chanHost = make(chan string, threads+1)
+		done     = make(chan struct{}, concurrency+1)
+		chanHost = make(chan string, concurrency+1)
 	)
 
 	var wg sync.WaitGroup
-	wg.Add(threads)
-	for i := 0; i < threads; i++ {
+	wg.Add(concurrency)
+	for i := 0; i < concurrency; i++ {
 		go func() {
 			for {
 				host, ok := <-chanHost
@@ -161,6 +98,92 @@ func ScanForAssets(hosts []string, ports []int, threads int, timeout int, disabl
 	return results
 }
 
+// GenerateHosts() builds a list of hosts to scan using the "subnet"
+// and "subnetMask" arguments passed. The function is capable of
+// distinguishing between IP formats: a subnet with just an IP address (172.16.0.0) and
+// a subnet with IP address and CIDR (172.16.0.0/24).
+//
+// NOTE: If a IP address is provided with CIDR, then the "subnetMask"
+// parameter will be ignored. If neither is provided, then the default
+// subnet mask will be used instead.
+func GenerateHosts(subnet string, subnetMask *net.IP) []string {
+	if subnet == "" || subnetMask == nil {
+		return nil
+	}
+
+	// convert subnets from string to net.IP
+	subnetIp := net.ParseIP(subnet)
+	if subnetIp == nil {
+		// try parse CIDR instead
+		ip, network, err := net.ParseCIDR(subnet)
+		if err != nil {
+			return nil
+		}
+		subnetIp = ip
+		if network != nil {
+			t := net.IP(network.Mask)
+			subnetMask = &t
+		}
+	}
+
+	mask := net.IPMask(subnetMask.To4())
+
+	// if no subnet mask, use a default 24-bit mask (for now)
+	return generateHosts(&subnetIp, &mask)
+}
+
 func GetDefaultPorts() []int {
 	return []int{HTTPS_PORT}
 }
+
+func rawConnect(host string, ports []int, timeout int, keepOpenOnly bool) []ScannedResult {
+	results := []ScannedResult{}
+	for _, p := range ports {
+		result := ScannedResult{
+			Host:      host,
+			Port:      p,
+			Protocol:  "tcp",
+			State:     false,
+			Timestamp: time.Now(),
+		}
+		t := time.Second * time.Duration(timeout)
+		port := fmt.Sprint(p)
+		conn, err := net.DialTimeout("tcp", net.JoinHostPort(host, port), t)
+		if err != nil {
+			result.State = false
+			// fmt.Println("Connecting error:", err)
+		}
+		if conn != nil {
+			result.State = true
+			defer conn.Close()
+			// fmt.Println("Opened", net.JoinHostPort(host, port))
+		}
+		if keepOpenOnly {
+			if result.State {
+				results = append(results, result)
+			}
+		} else {
+			results = append(results, result)
+		}
+	}
+
+	return results
+}
+
+func generateHosts(ip *net.IP, mask *net.IPMask) []string {
+	// get all IP addresses in network
+	ones, _ := mask.Size()
+	hosts := []string{}
+	end := int(math.Pow(2, float64((32-ones)))) - 1
+	for i := 0; i < end; i++ {
+		// ip[3] = byte(i)
+		ip = util.GetNextIP(ip, 1)
+		if ip == nil {
+			continue
+		}
+		// host := fmt.Sprintf("%v.%v.%v.%v", (*ip)[0], (*ip)[1], (*ip)[2], (*ip)[3])
+		// fmt.Printf("host: %v\n", ip.String())
+		hosts = append(hosts, ip.String())
+	}
+	return hosts
+}