Version: Current

Starting your First Scans

Now that you have installed the secureCodeBox, you can start you are close to being able to run your first scans.

Before we can start scans, we need to install their ScanTypes, these tell the secureCodeBox Operator how to run the scans and how their results can be parsed to create a uniform and consistent finding data model. ScanTypes are namespaced Custom Resource Definitions in Kubernetes, this lets different teams operating in different namespaces use different Types of scanners and enables them to define their own custom ScanTypes.

Installing the Nmap ScanType

In this guide, we'll use the Nmap Port & Network Scanner, as it is fast and relatively easy to use. We can install the Nmap ScanType via Helm (Make sure to add the helm repo first. See Installation):

helm install nmap secureCodeBox/nmap

To verify or to see which ScanTypes are installed in your current Namespace you can run:

kubectl get scantypes

This should print an output like this (your version might differ):

NAME   IMAGE
nmap   securecodebox/nmap:7.80

Starting a Scan

Now that we have the ScanType nmap installed, we are ready to start our first scan. A scanner, like this Nmap ScanType, is a namespaced CRD. That means you can install them in our own namespace and you're not required to have privileged access to the cluster. Also they are defined via YAML and so you can easily create your own ones.

This example creates a Nmap scan which probes the scanme.nmap.org host. This scan is equivalent to running nmap scanme.nmap.org locally.

caution

Please note the terms of usage for the http://scanme.nmap.org/ website. Basically, restrict yourself to run portscans and don't run crazy amounts of scans against it.

apiVersion: "execution.securecodebox.io/v1"
kind: Scan
metadata:
  name: "nmap-scanme.nmap.org"
spec:
  scanType: "nmap"
  parameters:
    - scanme.nmap.org

To run this example save the YAML above to a local file named nmap-scan.yaml and then start the scan via kubectl:

kubectl apply -f nmap-scan.yaml

The scan is now starting up, you can track its progress using kubectl:

kubectl get scans

This should print an output like this:

NAME                   TYPE   STATE      FINDINGS
nmap-scanme.nmap.org   nmap   Scanning

Monitoring the Scan Execution

When you apply a scan, the secureCodeBox Operator will create a Kubernetes Job in your namespace. In this namespace, the scanner (in our example the Nmap scanner) will be executed inside a container. Once the scan has completed the container will terminate and no compute resources will be consumed anymore. You can view the status of this job by running:

kubectl get jobs

This should give you an output like this

NAME                               COMPLETIONS   DURATION   AGE
parse-nmap-scanme.nmap.org-h8thd   1/1           30s        43m
scan-nmap-scanme.nmap.org-w66rp    1/1           10s        25s
note

Your job names will be slightly different. Kubernetes generates a random suffix for each job name to make them unique. In our case the suffix fir the scan job is -w66rp and for the parse job is -h8thd.

You can also view the logs of the container by running:

kubectl logs job/scan-nmap-scanme.nmap.org-w66rp nmap

If your job is still running you can stream the logs of the scan until it has completed:

kubectl logs job/scan-nmap-scanme.nmap.org-w66rp nmap --follow

This should print an output like this:

Starting Nmap 7.80 ( https://nmap.org ) at 2020-09-25 10:50 UTC
Nmap scan report for scanme.nmap.org (45.33.32.156)
Host is up (0.19s latency).
Other addresses for scanme.nmap.org (not scanned): 2600:3c01::f03c:91ff:fe18:bb2f
Not shown: 993 closed ports
PORT      STATE    SERVICE
22/tcp    open     ssh
80/tcp    open     http
135/tcp   filtered msrpc
139/tcp   filtered netbios-ssn
445/tcp   filtered microsoft-ds
9929/tcp  open     nping-echo
31337/tcp open     Elite
Nmap done: 1 IP address (1 host up) scanned in 5.44 seconds

Unless you are really quick or your scan took a long time you'll likely also seen that a second job was started:

kubectl get jobs

This should print an output like this:

NAME                               COMPLETIONS   DURATION   AGE
parse-nmap-scanme.nmap.org-sl56z   1/1           14s        15s
scan-nmap-scanme.nmap.org-w66rp    1/1           10s        25s

This second job takes the result of the Nmap Scan and transforms them into a secureCodeBox specific finding format. These findings share the same basic structure for all integrated scanners, which makes it very convenient to analyze them in further steps.

Viewing the Scan Results

Once this second job has completed you can get an overview of the results by taking another look at the scan:

kubectl get scans

This should print an output like this:

NAME                   TYPE   STATE   FINDINGS
nmap-scanme.nmap.org   nmap   Done    8

This list shows us the total count of findings identified by the scan. You can get a deeper overview by running:

kubectl describe scan nmap-scanme.nmap.org

This should print an output like this:

Name:         nmap-scanme.nmap.org
Namespace:    default
Labels:       <none>
Annotations:  API Version:  execution.securecodebox.io/v1
Kind:         Scan
Metadata:
  Creation Timestamp:  2020-09-25T10:50:09Z
  Finalizers:
    s3.storage.securecodebox.io
  Generation:        1
  Resource Version:  46608
  Self Link:         /apis/execution.securecodebox.io/v1/namespaces/default/scans/nmap-scanme.nmap.org
  UID:               fef73c4c-700a-4ad0-96c5-f8319989e9d9
Spec:
  Parameters:
    scanme.nmap.org
  Scan Type:  nmap
Status:
  Finding Download Link:  "...omitted for readability"
  Findings:
    Categories:
      Host:       1
      Open Port:  7
    Count:        8
    Severities:
      Informational:         8
  Finished At:               2020-09-25T10:50:35Z
  Raw Result Download Link:  "...omitted for readability"
  Raw Result File:           nmap-results.xml
  Raw Result Type:           nmap-xml
  State:                     Done
Events:                      <none>

This gives us an overview of the results of the scan. To view the actual findings produced by the scan you can use the download link to download the findings as JSON from Minio/S3.

Next Steps

Configure more Involved Nmap Scans

Nmap is an extremely powerful tool, which can be used for much more than just scanning for ports. You can find more examples of nmap scans, including example findings for these scans on the documentation page of the Nmap ScanType.

Other ScanTypes

Nmap is just one of the many security testing tools integrated into the secureCodeBox, you can find examples and documentation on how to use each of them on their documentation page in the sidebar.

To get started you can also take a look at our more detailed guides:

Persistence Providers

You can also integrate the secureCodeBox to automatically push the scan results into a external system like Elasticsearch or DefectDojo (Coming soon) to better analyse your findings.

Edit this page