Skip to main content

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   IMAGEnmap   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.

nmap-scan.yaml
apiVersion: "execution.securecodebox.io/v1"kind: Scanmetadata:  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      FINDINGSnmap-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   AGEparse-nmap-scanme.nmap.org-h8thd   1/1           30s        43mscan-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 UTCNmap 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:bb2fNot shown: 993 closed portsPORT      STATE    SERVICE22/tcp    open     ssh80/tcp    open     http135/tcp   filtered msrpc139/tcp   filtered netbios-ssn445/tcp   filtered microsoft-ds9929/tcp  open     nping-echo31337/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   AGEparse-nmap-scanme.nmap.org-sl56z   1/1           14s        15sscan-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   FINDINGSnmap-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.orgNamespace:    defaultLabels:       <none>Annotations:  API Version:  execution.securecodebox.io/v1Kind:         ScanMetadata:  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-f8319989e9d9Spec:  Parameters:    scanme.nmap.org  Scan Type:  nmapStatus:  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:                     DoneEvents:                      <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 an external system like Elasticsearch or DefectDojo (Coming soon) to better analyse your findings.