Most web applications will have specific pages that are only accessible to authenticated users. To effectively scan for vulnerabilities it is important to test all paths, including the authenticated routes.
HawkScan can support several styles of authentication. This includes traditional form-based username/password, http cookies, or several third party OAuth providers.
To set up Authenticated Scanning you will need to know the following 4 pieces of information about your application:
Login Authentication Type (AuthN)
The first step needed to set up Authenticated Scanning is your application’s Authentication Type (AuthN). HawkScan supports two types for AuthN. This could be a form (with a username and password) or an
externalsupplied authorization token. External authorization can come from services like Auth0, Amazon Cognito, Google, and Azure.
The simplest example is a username and password form.
Another form is through an API key or external auth provider.
Session Authorization Type (AuthZ)
The second step of information needed is how HawkScan should maintain authorization (AuthZ) throughout the scan. This can be done via a
tokenAuthorizationconfiguration. HawkScan also supports custom authentication scripts for more complex setups.
Upon verification the server returns a new cookie to the requesting client. The cookie is used to track your session on the server with the expectation that subsequent requests send the cookie back via the
Set-Cookieresponse header. This allows the server to track requests and maintain the session.
Bearer Token Authorization:
Many modern web application backends are APIs that serve data to more than just html based web browsers.
A common approach for authentication in this scenario is to create an API route that accepts a user’s credentials via a
POSTrequest of JSON data with the request returning an Authorization token as part of the JSON response payload.
Once the Authorization token is obtained, it is then passed by the client as an Authorization header on all subsequent requests to protected routes. This method of authorization is commonly referred to as bearer token authorization.
Custom authentication and session management scripts can be used to handle complex authentication and authorization scenarios. If a preconfigured authentication and/or authorization style doesn’t meet your needs you can replace either with a custom script.
Login Test Path
The third piece of information is a means of testing for successful authentication.
testPathconfiguration may also be provided to verify HawkScan authenticated its session correctly before scanning the application. The
testPathconfiguration also provides
requestBodyoptions to support alternate HTTP request verbs, such as
PUT. The default action is
Logged In/Out Indicators
The fourth and final piece relates to some data points that can tell HawkScan if it is logged in our out.
Throughout the scan, HawkScan will check to see if it is still logged in by the
loggedOutIndicator. These are regex strings to match against http responses from pages in the web application. This could be a “Log Out”/”Sign Out” button a user would see if logged in.
Based on your application you will pair a yml snippet of your authentication type with a snippet of how your authentication maintains credentials. The authentication and authorization configurations are defined separately to support a variety of web application needs.
Setting up Authenticated Scanning for your application will be highly dependent on the tech stack your team uses.
stackhawk.yml file will need to be edited to match your application’s specific needs.
StackHawk has created the Authenticated Scanning modal to get you started.
StackHawk has an Authenticated Scanning template builder to help get you started.
While on the Applications page, locate the desired Environment you would like to set up Authenticated Scanning for. On the Environment card, click the kabob menu in the top right corner. Select: “Setup Authenticated Scanning” to get started.
In this step, the helper needs information about your application’s authentication to best recommend a starting point.
Open the Authentication (AuthN) dropdown and select the choice that best matches your application’s authentication.
Sometimes authentication is not performed with just a username and password. For example, API key access or third-party authentication services like OAuth require custom tokens.
To support this type of authentication, HawkScan supports externally supplying an authorization token with the
The external supplied authorization token can be used in conjunction with either a token or a cookie to maintain the session. If you would like to supply authorization externally, select “Inject Cookie” or “Inject Token” depending on how your application maintains the session.
Select “Form with HTTP Parameters” or “Form with API Call / JSON Payload” if you would like to give HawkScan user credentials to use on a login page. You can either pull credentials in at run time or add them into your YAML file directly.
While the most basic form of authentication to set up, HawkScan needs to know what type of form is being used and what to capture after login to maintain the session (AuthZ).
After selecting your login form’s type, select how to maintain the session in the Authorization dropdown.
After giving the helper information about your application, a YAML snippet will be given and (if applicable) a link to download premade authentication scripts.
If you are using a 3rd party tool with a grant type that has premade scripts available, you will see a link to GitHub above your YAML Snippet.
Add the Auth Script folder next to your
stackhawk.yml and make adjustments as needed.
If you have decided to write your own scripts, refer to our GitHub repo.
Copy and paste this snippet into your
Based on the comments in your YAML snippet, edit and update your YAML file.
No matter what type of Authorization/Authentication your app is using, HawkScan requires
If you are unsure of how to update your YAML file, contact support.
Depending on how you set up your authentication, your run command may look different, however for most cases the run command is the same as before.
If you are using a script and/or put login credentials into your stackhawk.yml, the run command is the same as before setting up authentication.
If you are injecting a cookie, token, and/or login credentials at runtime, your run command will look different based on the environment variables you used in your configuration. Refer to the page on Running HawkScan and be prepared with the specific environment variables you used.
All available authentication configuration properties and values are explained in depth in the Authentication subsection of the Configuration docs.