Skip to content

Latest commit

 

History

History
207 lines (146 loc) · 12.2 KB

README.md

File metadata and controls

207 lines (146 loc) · 12.2 KB

Strelka Banner

Releases   |   Pull Requests   |   Issues

GitHub release Build Status Pull Requests Slack License

The Strelka Web UI is a browser and API-based file submission frontend for the Strelka Enterprise File Scanner. It allows users to submit files to a Strelka cluster and review historical response results easily. The Strelka Web UI supports LDAP authentication and API access, providing a secure and flexible way to interact with the Strelka scanner. This document provides details on how to set up and use the Strelka Web UI, as well as its features and related projects.

Strelka UI Results Page
Strelka UI Results Page

Features

The file submission UI provides the following features:

  • Submit files to a Strelka cluster and examine responses from your browser.
  • Store and review previous submission results and activity in either a local or remote database.
  • Support for LDAP Authentication
  • API support

Prerequisites

Quick Start

By default, the Strelka UI is configured to use a minimal "quickstart" deployment that allows users to test the system. This deployment will target a local Strelka instance and start a local database. Users will be able to access this system with whatever username / password they want. For additional information on targeting a remote Strelka instance, database, or using LDAP for authentication, see the Additional Setup section:

Step 1: Ensure a Strelka Cluster is Ready

Start or ensure Strelka cluster is ready and accessible.
See https://github.com/target/strelka for more information.

Step 2: Build and Start Strelka UI (Docker)

# Terminal 1
# From the ./strelka-ui directory
$ docker-compose -f docker-compose.yml up

Step 3: Access Strelka UI

1) Open A Browser
2) Navigate to 0.0.0.0:8080
3) Login with:
    - Username: strelka
    - Password: strelka

Additional Steps

This section provides details on how to target a remote Strelka instance, a remote database for storage, and an LDAP server for authentication for more secure use. To enable these, you can use environment variables to override the defaults.

Environment Variable Configuration

Backend configuration is provided through environment variables and can be set statically in ./app/config/config.py.

Running locally, the precedence of config is: System environment -> .env -> ./app/config/config.py. Running in Docker, the precedence of config is: Docker environment -> System environment -> ./app/config/config.py.

Please reference ./app/example.env for environment variable setup.

Environment Variable Options

The following detail the configuration items in ./app/config/config.py.

Field Name Value Required
STRELKA_HOST Strelka hostname (e.g., 0.0.0.0) Yes
STRELKA_PORT Strelka port number (e.g., 57314) Yes
STRELKA_CERT Path to certificate for Strelka, if needed (e.g., /path/to/cert.pem) No
CA_CERT_PATH Path to CA certificates for LDAP, if needed (e.g., /path/to/ca_certs) No
VIRUSTOTAL_API_KEY API Key for VirusTotal Hash Lookup Yes
VIRUSTOTAL_API_LIMIT Limit how many files should be scanned by VirusTotal (Default: 30) Yes
LDAP_URL URL to LDAP server (e.g., ldaps://ldap.example.com:636) No
LDAP_SEARCH_BASE Search base for LDAP queries (e.g., DC=example,DC=com) No
LDAP_USERNAME_ORGANIZATION Username organization for LDAP queries (e.g., org//) No
LDAP_ATTRIBUTE_ACCOUNT_NAME_FIELD LDAP attribute for account name (e.g., sAMAccountName) No
LDAP_ATTRIBUTE_FIRST_NAME_FIELD LDAP attribute for first name (e.g., givenName) No
LDAP_ATTRIBUTE_LAST_NAME_FIELD LDAP attribute for last name (e.g., sn) No
LDAP_ATTRIBUTE_MEMBER_OF_FIELD LDAP attribute for member of (e.g., memberOf) No
LDAP_ATTRIBUTE_MEMBER_REQUIREMENT_FIELD LDAP attribute for member requirement (e.g., AD Attribute) No
STATIC_ASSET_FOLDER Build folder for UI (e.g., build) Yes
MIGRATION_DIRECTORY SQLAlchemy migrations directory (e.g., ./migrations) Yes
DATABASE_USERNAME Database username (e.g., admin) Yes
DATABASE_PASSWORD Database password (e.g., password123) Yes
DATABASE_HOST Database hostname (e.g., db.example.com) Yes
DATABASE_PORT Database port number (e.g., 5432) Yes
DATABASE_DBNAME Name of the database (e.g., mydb) Yes
API_KEY_EXPIRATION Duration in days of API key expiration (e.g., 30) Yes
External Hotlink Support

You can also set a reference in the UI submission table to allow users to quickly pivot to an external site based on the request.id. By modifying ./ui/src/config.js and following the SEARCH_URL example in the following table, you can provide users with a link to an external site (e.g., SIEM / logger). Ensure your link has the string <REPLACE> in it and the UI will replace that string with the relevant file's request ID.

Supported modification fields in ./ui/src/config.js:

Field Name Value Example
SEARCH_URL Search URL for the external application Ex: https://search.com/?q=request.id=
SEARCH_NAME Search name for the external application Ex: Splunk
DEFAULT_EXCLUDED_SUBMITTERS Default users to be exluded from Submission table view. Useful for hiding automations by default. Ex: SearchBot

API

The Strelka UI also provides API routes for user script based access. Please reference the below routes for details:

Authentication routes

  • [base url]/api/auth/login (POST)
  • [base url]/api/auth/logout (GET)

Strelka routes

  • [base url]/api/strelka/scans/stats (GET)
  • [base url]/api/strelka/scans/upload (POST, form-encoded)
  • [base url]/api/strelka/scans?page=?&per_page=? (GET)
  • [base url]/api/strelka/scans/scan id

Example

Examples for how to authenticate to the Strelka UI API, gather Scan statistics, and Submit a file using Python requests can be found in ./misc/examples/api_examples.py

Database

The database uses https://www.sqlalchemy.org/ as an ORM. Flask-Migrate is used to provide db migrations though Alembic. A helper script file, manage.py, is provided to assist with common database tasks.

If you are creating a new database, or modifying the current one, you must perform the following steps - although upon starting the cluster, these commands will be executed for you:

Generate a new migration from model changes:

  • python manage.py db migrate

Update the database using the current database configuration

  • python manage.py db upgrade

Application Details

The backend application is predominantly comprised of the following technologies:

The frontend UI is a React JS application created using React served from Flask. The UI uses the Antd library and Antd ProComponents, and routing is handled by React Router.

Strelka UI Dashboard Page
Strelka UI Dashboard Page

Related Projects

Licensing

Strelka UI and its associated code is released under the terms of the Apache 2.0 License.

Target Banner