Configuring Muse

Following are .muse.toml configuration guides which encapsulate common workflows. For a more detailed reference of all Muse configuration options, see the Configuration Reference.

Languages

Java: Specifying Build System

Muse can guess which build system should be used in each directory by looking for common build files such as pom.xml, build.gradle, and gradlew. Sometimes the detected build is not preferred, perhaps because there are several such files present. An explicitly specified build can be used to disable the detection and assume one system. Consider the below example .muse.toml file that specifies use of Maven and jdk11:

build = "mvn"
jdk11 = true

Build targets, flags, and environmental variables can be added to to the build line too:

build = "gradle -DskipTests=true build"

NOTE: the build line is not executed verbatim. For each build system Muse has plugins to better understand the project files and dependencies. Normal behavior is if it builds then Muse will analyze the code but the difference surfaces rare cases. If the project’s build system is layered, such as a gradle build that just calls out to Maven, then the build will not be understood. If your project’s build falls into such a catagory then consider simplifying the build system and using a supported build system in a canonical manner.

Java: Android Projects

Android projects in Muse require special configuration. Android projects generally do not support JDKs later that 8, so the jdk11 flag should be set to false. The android SDK version is required to be specified for all android projects.

Here is an example configuration for an Android project:

build          = "gradlew"
arguments      = [ "assembleAndroidTest" ]
jdk11          = false
androidVersion = 28

Muse supports android SDK versions 27 and 28.

Java: Specifying Tools

For Java, Muse uses multiple tools to analyze the code. Documentation for each of these tools can be found here:

Errorprone - for common programming mistakes
FindSecBugs - security audits
Infer - potential bug finder

Muse is quiet by default. Large projects should consider further tuning Muse via explicit selection of which bugs to report and tools to run. For example, to run only Infer and FindSecBugs but ignore Infer’s RESOURCE_LEAK message use a configuration of:

tools = ["infer", "findsecbugs"]
ignore = ["RESOURCE_LEAK"]

C and C++

Muse supports C and C++ along with the common build systems of cmake, make, compilation databases, and GNU autotools including detecting then running autogen.sh and configure.

C and C++ analysis results are provided by Infer. Infer’s bug reference documentation can be found on their website. An example configuration that specifies the make build system and infer tool is:

build = "make"
tools = ["infer"]

As with java, the build line can specify environmental variables and argument but it is not itself a place to write arbitrary shell script. If it is necessary to execute a script prior to build then read the dependencies section.

If your project’s build system is complex then consider writing a setup script to generate a compilation database. For example define a .muse/setup.sh file of:

#!/usr/bin/env bash
# execute any build dependency steps here
apt update && apt install -y $DEPS
# Generate a compilation database next
CC=gcc compiledb -n make all

Then in the .muse/config.toml specify the build as compdb so Muse will ignore other build systems such as Make or CMake:

build = "compdb"
setup = ".muse/setup.sh"

The end results is you have full control over the compilation steps in a manner that is easy to inspect and debug.

JavaScript

ESLint is the tool that Muse uses to analyze Javascript projects. Muse respects ESLint configuration files and more information about the config files can be found on the website.

Muse runs ESLint by default. To run only ESLint make .muse.toml specfy the tools list as:

tools = ["eslint"]

Muse includes five additional commonly used configurations and plugins:

Each must be configured individually in order to be used. For example, in order to use the Airbnb configuration with hooks support, simply add "extends": ["airbnb", "airbnb/hooks"] to your .eslintrc. Other plugins and configurations can be installed if desired by using a setup script.

Python

Muse supports Python projects with Bandit and Pyre. By default, Pyre support operates by first finding requirements.txt or setup.py files, installing dependencies, and analyzing the project. Bandit will run on any repository containing files with the .py extension.

Ruby

Ruby is supported by Rubocop and, in the case of ruby on rails, Brakeman. Both these tools run when the repository contains files with the .rb extension.

Haskell

HLint is a Haskell analysis tool that is integrated with Muse. HLint can be configured by a .hlint.yaml at the working directory of the project. For more information on configuration, view HLint’s documentation

To run only HLint make .muse.toml specfy the tools list as:

tools = ["hlint"]

Environment Variables

Environment variables are defined in the build field of .muse.toml. For example, we can specify which C compiler to use when executing make:

build = "CC=gcc GXX=g++ CXX=g++ make"

Proxy settings with Bash environment variables can also be defined here.

build = "https_proxy=https://server:port make"

Local Settings

Some tools such as Maven use a settings.xml to specify custom artifactory servers. If the configuration file is not in the repository then the setup section of the Muse config can create that file.

setup = ".muse/createConfig.sh"

And the repository would include a .muse/createConfig.sh file of:

$ cat .muse/createConfig.sh
#!/usr/bin/env bash
mkdir ~/.m2
cat <<EOF > ~/.m2/settings.xml
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      https://maven.apache.org/xsd/settings-1.0.0.xsd">
  <localRepository>${user.home}/.m2/repository</localRepository>
  <interactiveMode>true</interactiveMode>
  <offline>false</offline>
  ...
</settings>
EOF

N.B. Muse does not currently have a secrets vault and can not inject secret information, such as Artifactory or Nexus credentials, into the analysis process.

Dependencies

Many projects require external depencies to be able to be built. We will look at some of the common ways to orchestrate muse to download and build these dependencies.

The Muse analysis image is based on Ubuntu 20.04. A complete list of included utilities is available here.

The following .muse.toml will be used for these examples and .muse/getDependencies.sh is defined in each example.

setup = ".muse/getDependencies.sh"

Downloading Through Github

Adding another repository that is a dependency from GitHib.

$ cat .muse/getDependencies.sh
#!/usr/bin/env bash
git clone github.com/<someuser>/<someproject>.git
cd someproject/ && make

Using Apt Package Manager

The server used to analyze is managed with the apt package manager providing access to a rich environment of packages.

$ cat .muse/getDependencies.sh
#!/usr/bin/env bash
apt update
apt install -y libcrypto-dev

Something Else

Is there any additional functionality you are missing? Check out the Muse “Bring Your Own Tool” API to learn how to extend Muse functionality with custom tools.

Still experiencing a build error or any other problem? We have a Troubleshooting page or feel free to contact us for personal assistance.

Docs