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

Prometheus metrics endpoint

Every Juice Shop instance offers a metrics endpoint (finding it is actually the hacking challenge Find the endpoint that serves usage data to be scraped by a popular monitoring system) to be consumed by the Prometheus monitoring system. Apart from "business" metrics and CPU/RAM usage the metrics contain summarized information about the current challenge progress on an instance of Juice Shop:

# HELP juiceshop_challenges_solved Number of solved challenges grouped by difficulty.
# TYPE juiceshop_challenges_solved gauge
juiceshop_challenges_solved{difficulty="1",app="juiceshop"} 0
juiceshop_challenges_solved{difficulty="2",app="juiceshop"} 0
juiceshop_challenges_solved{difficulty="3",app="juiceshop"} 0
juiceshop_challenges_solved{difficulty="4",app="juiceshop"} 0
juiceshop_challenges_solved{difficulty="5",app="juiceshop"} 0
juiceshop_challenges_solved{difficulty="6",app="juiceshop"} 0

# HELP juiceshop_challenges_total Total number of challenges grouped by difficulty.
# TYPE juiceshop_challenges_total gauge
juiceshop_challenges_total{difficulty="1",app="juiceshop"} 11
juiceshop_challenges_total{difficulty="2",app="juiceshop"} 10
juiceshop_challenges_total{difficulty="3",app="juiceshop"} 22
juiceshop_challenges_total{difficulty="4",app="juiceshop"} 23
juiceshop_challenges_total{difficulty="5",app="juiceshop"} 17
juiceshop_challenges_total{difficulty="6",app="juiceshop"} 11

Prometheus integration example

results matching ""

    No results matching ""