Merge pull request #11 from CiscoSecurity/develop

Release 1.0.0

.dockerignore

@@ -0,0 +1,2 @@
+code/tests
+code/observables.json

.gitignore

@@ -0,0 +1,12 @@
+# macOS
+.DS_Store
+
+# PyCharm
+.idea/
+
+# Python
+__pycache__/
+venv/
+
+# dotenv
+.env

Dockerfile

@@ -0,0 +1,25 @@
+FROM alpine:3.14
+LABEL maintainer="Ian Redden <[email protected]>"
+
+ENV PIP_IGNORE_INSTALLED 1
+
+# install packages we need
+RUN apk update && apk add --no-cache musl-dev openssl-dev gcc py3-configobj \
+supervisor libffi-dev uwsgi-python3 uwsgi-http jq syslog-ng uwsgi-syslog \
+py3-pip python3-dev
+
+# do the Python dependencies
+ADD code /app
+ADD code/Pipfile code/Pipfile.lock /
+RUN set -ex && pip install --no-cache-dir --upgrade pipenv && \
+    pipenv install --system
+RUN chown -R uwsgi.uwsgi /etc/uwsgi
+
+# copy over scripts to init
+ADD scripts /
+RUN mv /uwsgi.ini /etc/uwsgi
+RUN chmod +x /*.sh
+
+# entrypoint
+ENTRYPOINT ["/entrypoint.sh"]
+CMD ["/start.sh"]

Jenkinsfile

@@ -0,0 +1,3 @@
+@Library('softserve-jenkins-library@main') _
+
+startPipeline()

LICENSE.md

@@ -0,0 +1,22 @@
+
+The MIT License (MIT)
+
+Copyright (c) 2021 Cisco SecureX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1 +1,101 @@
-placeholder
+[![Gitter Chat](https://img.shields.io/badge/gitter-join%20chat-brightgreen.svg)](https://gitter.im/CiscoSecurity/Threat-Response "Gitter Chat")
+
+# Docker Relay Template (Cisco Hosted)
+
+A Cisco SecureX Concrete Relay implementation using [CyberScan](https://www.cyberscan.io/) 
+as a third-party Cyber Threat Intelligence service provider.
+
+The Relay itself is just a simple application written in Python that can be
+easily packaged and deployed in docker container.
+
+## Rationale
+
+- We need an application that will translate API requests from SecureX Threat Response to the third-party integration, and vice versa.
+- We need an application that can be completely self-contained within a virtualized container using Docker.
+
+## Testing (Optional)
+
+Open the code folder in your terminal.
+```
+cd code
+```
+
+If you want to test the application you have to install dependencies from the [Pipfile](code/Pipfile) file:
+```
+pip install --no-cache-dir --upgrade pipenv && pipenv install --dev
+```
+
+You can perform two kinds of testing:
+
+- Run static code analysis checking for any semantic discrepancies and
+[PEP 8](https://www.python.org/dev/peps/pep-0008/) compliance:
+
+  `flake8 .`
+
+- Run the suite of unit tests and measure the code coverage:
+
+  `coverage run --source api/ -m pytest --verbose tests/unit/ && coverage report`
+
+### Building the Docker Container
+In order to build the application, we need to use a `Dockerfile`.  
+
+ 1. Open a terminal.  Build the container image using the `docker build` command.
+
+```
+docker build -t tr-05-cyberscan .
+```
+
+ 2. Once the container is built, and an image is successfully created, start your container using the `docker run` command and specify the name of the image we have just created.  By default, the container will listen for HTTP requests using port 9090.
+
+```
+docker run -dp 9090:9090 --name tr-05-cyberscan tr-05-cyberscan
+```
+
+ 3. Watch the container logs to ensure it starts correctly.
+
+```
+docker logs tr-05-cyberscan
+```
+
+ 4. Once the container has started correctly, open your web browser to http://localhost:9090.  You should see a response from the container.
+
+```
+curl http://localhost:9090
+```
+
+## Implementation Details
+
+This application was developed and tested under Python version 3.9.
+
+### Implemented Relay Endpoints
+
+- `POST /health`
+  - Verifies the Authorization Bearer JWT and decodes it to restore the original
+  credentials.
+  - Authenticates to the underlying external service to check that the provided 
+  credentials are valid and the service is available at the moment.
+
+
+- `POST /observe/observables`
+  - Accepts a list of observables and filters out unsupported ones.
+  - Verifies the Authorization Bearer JWT and decodes it to restore the original credentials.
+  - Makes a series of requests to the underlying external service to query for some 
+  cyber threat intelligence data on each supported observable.
+  - Maps the fetched data into appropriate CTIM entities.
+  - Returns a list per each of the following CTIM entities (if any extracted):
+    - `Sighting`
+
+
+- `POST /refer/observables`
+  - Accepts a list of observables and filters out unsupported ones.
+  - Builds a search link per each supported observable to pivot back to the underlying external service and look up the observable there.
+  - Returns a list of those links.
+
+
+- `POST /version`
+  - Returns the current version of the application
+
+### Supported Types of Observables
+
+- `ip`
+- `domain`

build.sh

@@ -0,0 +1,32 @@
+#! /usr/bin/env sh
+echo " .:|:.:|:. "
+echo " C I S C O "
+echo "  SecureX "
+echo
+echo " Development Dockerfile build script."
+echo
+
+module_name="Docker relay"
+image_name="tr-05-docker-relay"
+
+CONFIG_FILE=code/container_settings.json
+if [ -f $CONFIG_FILE ]; then
+   echo
+   echo "The configuration file (container_settings.json) already exists."
+   echo
+   version=`jq -r .VERSION code/container_settings.json`
+else
+   read -p 'Version: ' version
+   echo {\"VERSION\": \"$version\", \"NAME\": \"$module_name\"} > code/container_settings.json
+fi
+
+echo " Integration Module: $module_name"
+echo "            Version: $version"
+echo
+echo "Starting build process ..."
+echo
+docker build -t "$image_name:$version" .
+
+echo
+echo "Please ensure you update module_type.json with correct url."
+echo

code/Pipfile

@@ -0,0 +1,19 @@
+[[source]]
+url = "https://pypi.org/simple"
+verify_ssl = true
+name = "pypi"
+
+[packages]
+cryptography = "==3.3.2"
+Flask = "==2.0.1"
+marshmallow = "==3.12.1"
+requests = "==2.25.1"
+PyJWT = "==2.1.0"
+
+[dev-packages]
+flake8 = "==3.9.2"
+coverage = "==5.5"
+pytest = "==6.2.4"
+
+[requires]
+python_version = "3.9"