Skip to main content

As Scala Library

Describes how to use recheck as a Scala library.

Install​

Maven Central

To install the Scala library of recheck, you should append the following line into your build.sbt.

build.sbt
libraryDependencies += "codes.quine.labs" %% "recheck-core" % "5.0.0-beta.2"

Usage​

ReDoS.check is the only entry point for checking the vulnerability of regular expression.

import codes.quine.labs.recheck.ReDoS

ReDoS.check("^(a|a)*$", "")

The first argument of ReDoS.check is the source which is corresponding to RegExp.prototype.source. And, the second argument is the flags which is corresponding to RegExp.prototype.flags too. The third argument is the params to specify parameters for the checker behavior, and the fourth is the token to cancel the checking in the middle. The dialect parameter (e.g. Parameters(dialect = Dialect.Python()) or Parameters(dialect = Dialect.Python(Dialect.Python.Type.Bytes)) with codes.quine.labs.resyntax.dialect.Dialect) checks a regular expression of another language (see Dialects).

info

See this page for detailed information on Parameters value.

The result of ReDoS.check is called Diagnostics. It is the evidence for judging the ReDoS risk of the regular expression, not a final verdict. Diagnostics is a sealed class, and it has three child classes.

  • Diagnostics.Safe means that the checking found no attack string within its limits.
  • Diagnostics.Vulnerable means that the checking found an attack string.
  • Diagnostics.Unknown means that the checking could not finish (timeout, cancel, or error).
info

See this page for detailed information on the Diagnostics value.

Cancel​

The fourth argument of ReDoS.check is used to cancel the checking in the middle. This type is CancellationToken which is created by CancellationTokenSource. Noting that ReDoS.check blocks the process, you should use this with concurrent libraries like scala.concurrentor cats-effect.

The following example is usage with cats-effect.

import scala.concurrent.duration._

import cats.effect._
import cats.effect.unsafe.implicits.global

import codes.quine.labs.recheck.ReDoS
import codes.quine.labs.recheck.common.CancellationTokenSource
import codes.quine.labs.recheck.common.Parameters
import codes.quine.labs.recheck.diagnostics.Diagnostics

val cancellation = new CancellationTokenSource

val io = for {
fiber <- IO(ReDoS.check("^a+a+$", "", Parameters(), Some(cancellation.token))).start
_ <- (IO.sleep(100.millisecond) *> IO(cancellation.cancel())).start
diagnostics <- fiber.joinWithNever
_ <- IO.println(diagnostics)
} yield ()

io.unsafeRunSync()
caution

There is the timeout parameter to specify timeout seconds. Please use this instead of the manual way.

note

The above example does not work with cats-effect better actually, because fiber has cancel method and it does not work with this method.

To fix this problem, we can use IO.async. The following is the complete example. However, because of a restriction of cats-effect, it loses the diagnostics when a fiber is cancelled.

import scala.concurrent.duration._

import cats.effect._
import cats.effect.unsafe.implicits.global

import codes.quine.labs.recheck.ReDoS
import codes.quine.labs.recheck.common.CancellationTokenSource
import codes.quine.labs.recheck.common.Parameters
import codes.quine.labs.recheck.diagnostics.Diagnostics

def cancelableCheck(source: String, flags: String, params: Parameters): IO[Diagnostics] =
IO.executionContext.flatMap { ec =>
IO.async { cb =>
IO {
val cancellation = new CancellationTokenSource
ec.execute(() => {
val diagnostics = ReDoS.check(source, flags, params, Some(cancellation.token))
cb(Right(diagnostics))
})
Some(IO(cancellation.cancel()))
}
}
}

val io = for {
fiber <- cancelableCheck("^a+a+$", "", Parameters()).start
_ <- (IO.sleep(100.millisecond) *> fiber.cancel).start
diagnostics <- fiber.join
_ <- IO.println(diagnostics)
} yield ()

io.unsafeRunSync()