shfzlib

Scenario-based fuzzing test execution tool's scenario library.

Install

https://www.npmjs.com/package/shfzlib

npm i shfzlib

Setup

Installation of Node.js, npm and shfz/shfz is required.

TypeScript

Setup npm project

$ mkdir fuzz-project
$ cd fuzz-project
$ npm init
$ npm install typescript @types/node shfzlib

$ touch tsconfig.json

{
  "compilerOptions": {
    "target": "esnext",
    "module": "commonjs",
    "moduleResolution": "node",
    "strict": true,
    "skipLibCheck": true,
    "declaration": true,
    "pretty": true,
    "newLine": "lf",
    "outDir": "dist"
  },
  "exclude": [
    "node_modules"
  ]
}

Edit fuzzing scenario script. (For this scenario, fuzz shfz/demo-webapp running in your local environment.)

$ touch scenario.ts

import { Shfzlib, Charset } from "shfzlib";

const sh = new Shfzlib("http://localhost");

(async () => {
  const username = await sh.fuzz.gen("username", Charset.lowercase(), 12, 8, false);
  const password = await sh.fuzz.gen("password", Charset.ascii(), 16, 8, false);

  await sh.http.postForm("POST /register", "/register", { username, password });
  await sh.http.postForm("POST /login", "/login", { username, password });

  const title = await sh.fuzz.gen("title", Charset.lowercase(), 16, 8, false);
  const text = await sh.fuzz.gen("text", Charset.ascii(), 16, 8, false);

  await sh.http.postForm("POST /memo", "/memo", { title, text });

  await sh.http.done();
})();

Run shfz/demo-webapp and shfz server, then execute scenario script by shfz run.

$ cd demo-webapp
$ docker-compose up

$ shfz server

$ ./node_modules/.bin/tsc scenario.ts
$ shfz run -f scenario.js -n 10 -p 1 -t 30

Usage

Initialize

import { Shfzlib, Charset } from "shfzlib";

Shfzlib contains http request function and fuzz generate function. char contains some typical character sets.

const sh = new Shfzlib("http://localhost");

Create an instance of Shfzlib. The argument is baseURL of the web application to be fuzzng.

The session information for a series of http requests is stored in the AxiosInstance. (The cookie is held by axios-cookiejar-support)

fuzz generate fl.fuzz

sh.fuzz.gen("username", Charset.lowercase(), 12, 8, false);

gen(name: string, charset: string, maxLen?: number, minLen?: number, isGenetic?: boolean): Promise<string>;

If isGenetic of sh.fuzz.gen is true and the trace library is installed in the web application, fuzz will be generated by the genetic algorithm.

http request sh.http

This library is an extension of axios, and in many cases allows you to add the same options as in axios. Please refer TypeScript type information for details.

Note : In this script, async/await is used. These http requests need to be wrapped with async.

GET

sh.http.get("API Name", "/path");

get(name: string, url: string, config?: AxiosRequestConfig): Promise<AxiosResponse>;

POST (json)

sh.http.post("API Name", "/path", { "param": param });

post(name: string, url: string, data?: any, config?: AxiosRequestConfig): Promise<AxiosResponse>;

POST (form)

sh.http.postForm("API Name", "/path", { "param": param });

postForm(name: string, url: string, data?: any, config?: AxiosRequestConfig): Promise;

PUT

sh.http.put("API Name", "/path", { "param": param });

put(name: string, url: string, data?: any, config?: AxiosRequestConfig): Promise<AxiosResponse>;

PATCH

sh.http.patch("API Name", "/path", { "param": param });

patch(name: string, url: string, data?: any, config?: AxiosRequestConfig): Promise<AxiosResponse>;

DELETE

sh.http.delete("API Name", "/path");

delete(name: string, url: string, config?: AxiosRequestConfig): Promise<AxiosResponse>;

HEAD

sh.http.head("API Name", "/path");

head(name: string, url: string, config?: AxiosRequestConfig): Promise<AxiosResponse>;

OPTIONS

sh.http.options("API Name", "/path");

options(name: string, url: string, config?: AxiosRequestConfig): Promise<AxiosResponse>;

Finish http request

You need to call await sh.http.done(); to aggregate the errors when all http requests are finished.

Record custom error

You need to call await sh.http.error("error message"); to record custom errors such as whether the response contains certain characters.

Example) check username is in response

import * as c from "cheerio";

...

  let $ = c.load(res.data);
  if($('p[id="user"]').text() !== username) {
    await sh.http.error("No username in response");
  };

Charset

• Charset.ascii() : !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_'abcdefghijklmnopqrstuvwxyz{|}~
• Charset.symbol() : !"#$%&'()*+,-./:;<=>?@[\]^_{|}~`
• Charset.number() : 0123456789
• Charset.lowercase() : abcdefghijklmnopqrstuvwxyz
• Charset.uppercase() : ABCDEFGHIJKLMNOPQRSTUVWXYZ

Customize

The scenario is written in Javascript and Typescript, any npm package can be installed.

Here's a digest of the recommended npm packages and how to use them.

Response body check

import * as c from "cheerio";

...

  let res = await sh.http.postForm("login api", "/login", { username, password });
  let $ = c.load(res.data);
  if($('p[id="user"]').text() !== username) {
    await sh.http.error("No username in response");
  };

Generate TOTP

import * as c from "cheerio";
const totp = require("totp-generator");

...

  // get totp_secret by cheerio
  let res = await sh.http.postForm("register api", "/register", { username, password });
  let $ = c.load(res.data);
  let totp_secret = $('p[id="totp"]').text();
  await sh.http.get("/logout");

  // generate one time password by totp package
  const one_time_password = totp(totp_secret)

  // login with one time password
  await sh.http.postForm("login api", "/login", { username, password, totp: one_time_password });

CSRF Token

import * as c from "cheerio";

...

  // get csrf_token
  let res = await fl.http.get("register page", "/register");
  let $ = c.load(res.data);
  let csrf_token = $('input[name="csrf_token"]').val()

  // POST register form with csrf_token
  await fl.http.postForm("register api", "/register", { username, password, csrf_token: csrf_token });