Integration

OWASP Juice Shop follows strict conventions for describing challenges. These allow you to easily integrate Juice Shop tutorials, hints and solutions into your own security guides, knowledge bases, testing labs etc.

Challenges API

The endpoint /api/Challenges on your local Juice Shop instance (i.e. http://localhost:3000/api/Challenges) returns information on the configured challenges along with their current state in an easily consumable JSON format:

{
   "status":"success",
   "data":[
      {
         "id":1,
         "key":"restfulXssChallenge",
         "name":"API-only XSS",
         "category":"XSS",
         "description":"Perform a <i>persisted</i> XSS attack with <code>&lt;iframe src=\"javascript:alert(`xss`)\"&gt;</code> without using the frontend application at all. <em>(This challenge is <strong>not available</strong> on Heroku!)</em>",
         "difficulty":3,
         "hint":"You need to work with the server-side API directly. Try different HTTP verbs on different entities exposed through the API.",
         "hintUrl":"https://pwning.owasp-juice.shop/part2/xss.html#perform-a-persisted-xss-attack-without-using-the-frontend-application-at-all",
         "solved":false,
         "disabledEnv":"Heroku",
         "createdAt":"2020-03-23T12:00:34.258Z",
         "updatedAt":"2020-03-23T12:00:34.258Z"
      },
      {
         "id":2,
         "key":"accessLogDisclosureChallenge",
         "name":"Access Log",
         "category":"Sensitive Data Exposure",
         "description":"Gain access to any access log file of the server.",
         "difficulty":4,
         "hint":"Who would want a server access log to be accessible through a web application?",
         "hintUrl":"https://pwning.owasp-juice.shop/part2/sensitive-data-exposure.html#gain-access-to-any-access-log-file-of-the-server",
         "solved":false,
         "disabledEnv":null,
         "createdAt":"2020-03-23T12:00:34.259Z",
         "updatedAt":"2020-03-23T12:00:34.259Z"
      },
      {
        "...":"..."
      }
   ]
}

Instead of your own local instance you can also use the API of the publicly available demo instances to pull challenge information:

🚨 There is no uptime guarantee for either of these as they are both only free Heroku dynos. Please refrain from making unnecessary amounts of requests.

API integration example

Challenge declaration file

The single source of truth for challenges in OWASP Juice Shop is its data/static/challenges.yml file. It is used during start-up of the application to populate the Challenges table which is then exposed via the Challenges API endpoint.

Parsing this file directly for integration makes sense when you do not rely on changed settings (e.g. hints being turned off) from an individual Customization and/or you do not have a running Juice Shop instance available in the first place.

-
  name: 'Some Name'
  category: 'Category of the challenge'
  description: 'Here the actual task for the attacker is described.'
  difficulty: 1 # a number between 1 and 6
  hint: 'A text hint to display on the Score Board when hovering over the challenge'
  hintUrl: 'https://pwning.owasp-juice.shop/part2/<category>.html#<shortened description>'
  key: someNameChallenge
  disabledEnv: # (optional) to disable challenges dangerous or incompatible in certain environments
    - Docker
    - Heroku
    - Windows
  tutorial: # (optional) present only on challenges with a Hacking Instructor tutorial
    order: 1 # a unique number to specify the recommended order of tutorials

The latest versions of the challenges.yml file can be found here:

Description Link composition Condition Examples
Link to official hints for a specific challenge <hintUrl> https://pwning.owasp-juice.shop/part2/score-board.html#find-the-carefully-hidden-score-board-page or https://pwning.owasp-juice.shop/part2/xss.html#perform-a-dom-xss-attack
Link to official step-by-step solution for a specific challenge https://pwning.owasp-juice.shop/appendix/solutions.html#<hash part of hintUrl> https://pwning.owasp-juice.shop/appendix/solutions.html#find-the-carefully-hidden-score-board-page or https://pwning.owasp-juice.shop/appendix/solutions.html#perform-a-dom-xss-attack
Direct link to a Hacking Instructor tutorial for a specific challenge /#/hacking-instructor?challenge=<name> Only for challenges where tutorial is defined. http://localhost:3000/#/hacking-instructor?challenge=Score%20Board or http://preview.owasp-juice.shop/#/hacking-instructor?challenge=DOM%20XSS

🖼️ As the utilized GitBook version does not set the x-frame-options header, it is possible to display content from https://pwning.owasp-juice.shop in an <iframe>.

YAML integration example

Challenge solution webhook

Any Juice Shop instance can be configured to call a webhook whenever one of its 95 hacking challenges is solved. To use this feature the following environment variable needs to be supplied to the Juice Shop server:

Environment variable Expected value Recommendations
SOLUTIONS_WEBHOOK URL of the webhook Juice Shop is supposed to call whenever a challenge is solved. The webhook URL should be bound to the user who solved the challenge and allow its provider to verify the Juice Shop origin instance. In most cases the webhook URL should be treated as sensitive information and not be published or transmitted unencrypted!

Webhook payload

Juice Shop will send a POST request to the configured SOLUTIONS_WEBHOOK with the following payload:

{ "solution":
  { "challenge": "<'key' of the solved challenge from ./data/static/challenges.yml>",
    "evidence": null,
    "issuedOn": "<yyyy-MM-ddThh:mm:ssZ>"
  },
  "issuer": {
    "hostName": "<server os hostname>",
    "os": "<server os type (and release)>",
    "appName": "<'application.name' from loaded YAML configuration in ./config folder>",
    "config": "<name of the loaded configuration>",
    "version": "<version from ./package.json>"
  }
}

Webhook payload example

{
  "solution": {
    "challenge": "localXssChallenge",
    "evidence": null,
    "issuedOn": "2020-05-26T22:03:20.059Z"
  },
  "issuer": {
    "hostName": "Traviss-Mac-6.local",
    "os": "Darwin (17.7.0)",
    "appName": "OWASP Juice Shop",
    "config": "default",
    "version": "11.0.0"
  }
}

results matching ""

    No results matching ""