# Meterian What is Meterian? The Meterian Platform is a fuss-free and instant solution to protect you against vulnerabilities in your app’s software supply chain. The supply chain of open source components underpins the cornerstone that speeds up innovation. With only 10% of proprietary software code written by developers who are stretched for time, they leverage the speed and convenience of open source to provide basic functionality and security. However, the stability and security of the app are not guaranteed forever. With Meterian, you can automate the due diligence of identifying and patching open source risks in minutes. Immediately see if the code your team didn't write is free of security, stability and licensing risks. Mitigate with Meterian to secure your apps'​ dependent software components while you focus on innovating. {% embed url="" %} Watch a one minute introduction! {% endembed %} Check out how to [run your first scan](/the-client/guide-your-first-scan) with Meterian! # The Platform The Meterian platform is composed of three different scanning systems: * a [scanner for codebases](/the-client/client) (SCA - Software Composition Analysis) * a [scanner for containers](/containers-support/container-scanner) (SCA - Software Composition Analysis for docker containers) * a [scanner for infrastructure-as-code](/dedicated-instance/using-the-scanners/iac-scanner) (IaC scanner) Our license is generally based on the number of assets you want to keep under control (codebases, docker images, IaCs): the cost will depend on how many of them you want to keep it in the platform. We can also license the system based on seats, if needed. All languages and CI integrations supported are included in all commercial plans. Some reporting formats may not be available to non-enterprise licenses. [Support](/master/support) is included in all commercial plans. Some additional features need to be inclduded explicitly: * teams management * automatic [notifications](/notifications/sentinel) of new vulnerability in codebases without explicit scanning * software bill of materials ([SBOMS](/the-meterian-webapp/advanced-functionalities/software-bill-of-materials-sbom)) * full [API access](/api-basics) * license inventory and [risk analysis](/the-meterian-webapp/the-web-dashboard-1/policies) * [automatic remediation ](/the-client/command-line-parameters/advanced-options/autofix)and[ pull-requests](/the-client/command-line-parameters/advanced-options/pull-requests) (on selected platforms and languages) # SSO and MFA The platform offers different options for authentication, including multiple SSO (Single Sign On) options and, on top of any of those, also MFA (Multi Factor Authentication) if/when required. Access via credentials (standard username+password) powered by third-party or by Meterian is included in all plans. Access via social logins (GoogleWorkspace, Github, etc.), powered by third-party is also included in all plans Please note that SSO and MFA may incur additional costs. ### SSO - Single sign on SSO is available to all enterprise pla: * native SSO provided by Meterian and supporting: * AzureAD/Entra via OAuth2/OIDC * AzureAD/Entra via SAML * Google Workspace * Cognito * OpenAM * Generic SAML connector * user provisioning via SCIM connector * third-party SSO, supports all most popular external configurations, up to 2000 users * ad-hoc SSO implementations Additional specific documentation can be provided via support request ### MFA - Multi Factor Auhentication In terms of MFA we offer two options that can be put on top of the selected authentication mechanism: * up to 2 factors: authenticator/OTP, recovery codes) * up to 4 factors: authenticator/OTP, recovery codes, email, sms Additional information can be found in the [specific section](/the-meterian-webapp/advanced-functionalities/multi-factor-authentication). # Support Our support is generally available via the email , 8x5 UK time, excluding bank holidays . Our support team is managed by engineers (real people, not AI) who are in rotation: you will always speak to somebody who has a deep technical understanding of the problem and knows the system well. Additional support via chat (usually Slack) is also commercially available: this guarantees very quick turnarounds for any problem, and also provides you with a very efficient way to solve your issues. Special agreements can be put in place for extended support hours, usually with a specific MSA. # The Thin Client The Meterian thin client is used to securely execute a scan of your project without the need of providing access to your local source control system. If you want to do an occasional scan on your private project or you want to add the scan to your CI/CD pipeline the client is the most obvious choice. With the client all the information related to your project will be securely stored and linked to your account: no data will be publicly available at any point in time. To access historical information, status and reports you will always have to log in first. You will be requested to login to access any private report. To use the client first of all [download the latest version](https://www.meterian.com/downloads/meterian-cli.jar) and move it in a folder of your choice (e.g.: /tmp); now, using your system command line, simply navigate to your project' folder, make sure the build tool for your project' language is installed and your project correctly compiles, and then simply execute the command ``` $ java -jar /tmp/meterian-cli.jar ``` Please note that the thin client does not include any standard SDK that is usually needed to produce the dependencies graph of your application. For example, if you want to analyse a Java project based on Maven, then Maven will have to be installed on your machine. The same happens if you want to analyse a .NET project: the .NET SDK will have to be installed and correctly configured on the machine you are running the client from. We expected developers to have their tools in their machines :) but in case they do not, please prefer using the[ dockerized version of the client](/the-client/the-meterian-client-dockerized), which includes also all the necessary tools. If you are Windows user please refer to the specific section "[Using the thin client on Windows](/the-client/client/use-the-thin-client-on-windows)". # How does the client work? The client will first authenticate and validate your account: you can review the details of the operation in the related section. You will need to run the client in the folder where your project is located. The client will scan the folder searching for the files where your dependencies are listed or it will invoke the relevant tool to generate them. Once the list of dependencies is available it will be then uploaded securely to the Meterian servers, where the analysis will be conducted. Please note that if you decided to run the analysis remotely, which is available for some platforms, then all the build files will be uploaded instead (see the related chapter for more information). The client will be reporting the progress of the operation in its various stages, and at the end, it will print out the scores, with a link to securely access the full report. Multiple analysers can be automatically triggered: you can get manual control over this. see the section [Forcing or avoiding specific scans](/the-client/general-operations/forcing-or-avoiding-specific-scans). Some analyzers can also work recursively: in order to control that behaviour, see the section about [Excluding specific folders](/the-client/general-operations/excluding-specific-folders). # How does the client authenticate me? The client can be used in interactive and non-interactive mode, depending on the operation being monitored by a human or not, and of course by your choice. **In interactive mode** (which is the default) the client will check if it has a valid authorization and, if not, will open for you a browser window so that you can log in with your credentials. After a successful login, the client will securely store an authorization token in your home folder, so that you will not need to log in for a certain amount of time. Depending on your configuration, this can vary from hours to days, but by default, a token obtained in this way will last 24 hours. **In non-interactive mode**, used on servers or CI/CD platforms, you will need to generate a token on the [dashboard](https://www.meterian.com/dashboard) and then store it as a file on the local file system. When you will launch the client you will have to specify where the token is stored so that the client can authenticate on your behalf. ``` $ java -jar /tmp/meterian-cli.jar --interactive=false --auth-file=/tmp/tokens/mytoken.json ``` The client also reads the environment variable **METERIAN\_API\_TOKEN** which can be preloaded with the value of the token, as visible from the [dashboard ](https://www.meterian.com/dashboard#tokens)page, in the UUID format "01234567-890a-bcde-f012-34567890abc"). We suggest to export this variable in your login script or, if running on a CI/CD platform, using the secrets configuration available there. 
In your login script:
export METERIAN_API_TOKEN=1234fd34-..."

During normal operation:
$ java -jar /tmp/meterian-cli.jar
For detailed information please see the instructions section in your administration page. # How do I get the client? Please login from our [main page](https://www.meterian.com/) and follow the instructions provided in the [dashboard](https://www.meterian.io/dashboard), there is also a [permalink](https://www.meterian.com/downloads/meterian-cli.jar) you can use for that purpose. # What if I need a previous release? Please contact our [support email](mailto:support@meterian.com). # Use the thin client on Windows #### Install the Java Runtime The Java Thin Client requires a working copy of the JRE (Java Runtime Environment) that can be freely downloaded from [java.co](https://java.com/)[m](https://java.com/) and installed with a wizard. It can also be simply unpacked and referenced in the PATH variable from a standard archive which can be downloaded from [openjdk.net](https://openjdk.java.net/) (see detailed instruction there). To check that everything is working correctly after installing the JRE we can run "java --version" from either PowerShell or the standard Windows Command Prompt ``` PS C:\Users\John> java -version java version "1.8.0_271" Java(TM) SE Runtime Environment (build 1.8.0_271-b09) Java HotSpot(TM) Client VM (build 25.271-b09, mixed mode, sharing) ``` ``` C:\Users\John>java -version java version "1.8.0_271" Java(TM) SE Runtime Environment (build 1.8.0_271-b09) Java HotSpot(TM) Client VM (build 25.271-b09, mixed mode, sharing) ``` At some point, as usual, Windows may ask you for permissions to execute the Java runtime: please allow the execution. ![Allowing the execution of the Java runtime](/files/-MOYE-XcXpwuU1SEUqik) #### Download the Java Thin Client To use the client first of all [download the latest version](https://www.meterian.com/downloads/meterian-cli.jar), it will be put under your standard Windows "Downloads" folder. Now let's verify that everything is working as expected, launching the client for the first time and asking it to print its version. As you can see we are using the command "java -jar" followed with the full path to the newly downloaded meterian client file ("C:\Users\John\Downloads\meterian-cli.jar") and the command "--version" ``` PS C:\Users\John> java -jar C:\Users\John\Downloads\meterian-cli.jar --version 1.2.11.4.210e362-473 ``` ``` C:\Users\John>java -jar C:\Users\John\Downloads\meterian-cli.jar --version 1.2.11.4.210e362-473 ``` The client promptly answers with its version number (please note that this may be different from the one shown here). #### Executing the first analysis Now we also need some code to verify that an analysis can be executed: make sure you have such project and also the tools required to compile, as the thin client does not contain any development tools. Now you just move into such folder and run the client with "java -jar" followed with the full path to the newly downloaded meterian client file. If this is not a project managed bit a source control system (for example if you downloaded the sample project) you will also need to specify a "--project-url=" followed with a unique name or URL to identify your project later on your Dashboard. ``` C:\Users\John> cd \Users\John\Projects\Example C:\Users\John\Projects\Example> java -jar C:\Users\Bruno\Downloads\meterian-cli.jar --project-url=sample ``` If this is the first time you have ever used the client the system will open a new browser window asking you to authenticate to the Meterian platform: ![A new browser window is opened to authenticate the user](/files/-MOYH1NkfcH6lO1T0eLI) Alternatively, you can alsoset up the METERIAN\_API\_TOKEN environment variable with one of [tokens available in the account](https://www.meterian.com/dashboard#tokens), or create a new one. 
PS C:\Users\John> set METERIAN_API_TOKEN=your-token-uuid-here
The client will proceed in the analysis, providing progress information, and at the end, it will also provide an URL of the project it was just scanned: You can open that URL with any browser and see the results of the analysis, the client will display only the resulting scores ``` PS C:\Users\John\Projects\Example> java -jar C:\Users\Bruno\Downloads\meterian-cli.jar --project-url=sample Meterian Client v1.2.11.4, build 210e362-473 All rights reserved - running locally: yes - interactive mode: on - working on folder: C:\Users\John\Projects\Example - autofix mode: off Checking folder... Folder C:\Users\John\Projects\Example contains a viable project! Authorizing the client... Client successfully authorized Account: "Meterian Team Account" - Minimum scores: - security: 90 - stability: 90 - licensing: 90 - Analysis scopes: - security: packaged components - stability: all components - licensing: all components Loading build status... No build running found! Requesting build... Build allowed Project information: - url: sample - branch: head - commit: n/a NodeJS scan - running npm version 6.14.6 locally... - npm: npm dependencies succesfully generated from package.lock... Execution successful! Uploading dependencies information - 2 found... Done! Starting build... Current build status: in preparation Current build status: process advices at 2020-12-14T22:09:01.418 Final results: - security: 100 (minimum: 90) - stability: 100 (minimum: 90) - licensing: 100 (minimum: 90) Full report available at: https://www.meterian.com/projects/?pid=6ad085de-c701-4f6f-93cb-ef3672f6a2a9&branch=head&mode=eli Build successful! ``` ![](/files/-MOYJPWfZ3cKhPKdNyc2) Congratulations! Your installation on Windows is complete. #### What if maven is not executing? It may happen if your maven installation is non-standard. In that situation you need to inform the client about where the maven binary is and how it's called, this can be done using one of the [Maven specific controls](/the-client/command-line-parameters/specific-controls/maven-specific-controls), `maven.binary`, like in this example: 
PS C:\Users\John> java -Dmaven.binary="%MAVEN_HOME%\bin\mvn.cmd" -jar C:\Users\Bruno\Downloads\meterian-cli.jar
# Using the client from your command line From time to time you may want to do the occasional check on your project, or you are just evaluating a project and you want to check how it scores. In that case you may want to run the client in **interactive mode**: the client will assume that a person is present and ready to react to any issue. The quite common case is to provide a login to a Meterian account: as your results will be computed in the cloud, you want to maintain those completely private, and for that reason you will need to provide the client an authorization token linked to your account. By default the client runs in interactive mode. # Authorization in interactive mode In interactive mode the client will check if you have a valid authorization and, if not, will open for you a browser window so that you can log in with your credentials. After a successful login, the client will securely store an authorization token in your home folder, so that you will not need to log in for a certain amount of time. Depending on your configuration, this can vary from hours to a day, but by default, a token obtained in this way it will last 24 hours. # Interrupting the client The client stores the state of its progress in a hidden folder under your home, and can be interrupted at any time. When you are ready to resume it, you just need to launch it in the same folder and it will start exactly from the point where it stopped: the state of the operation is preserved on the Meterian servers. Please note that the client will refuse to execute another analysis if the previous one is still in progress: you can override this behavior passing the --clean parameter to the command line, which will remove any pending build, starting a new one. ``` $ java -jar /tmp/meterian-cli.jar --clean ``` # Example: running the client in interactive mode Let's run this example with a simple open source project you can find on GitHub; for this exercise let's assume also you already downloaded and stored the client under `~/apps/Meterian-cli.jar` First, let's clone the project from GitHub, for example Eclipse Vert.x: ``` $ git clone git@github.com:eclipse/vert.x.git Cloning into 'vert.x'... remote: Counting objects: 110122, done. remote: Compressing objects: 100% (86/86), done. remote: Total 110122 (delta 81), reused 145 (delta 61), pack-reused 109941 Receiving objects: 100% (110122/110122), 94.48 MiB | 1.20 MiB/s, done. Resolving deltas: 100% (57513/57513), done. Checking connectivity... done. ``` Now, let's move into the folder and launch the client with the default configuration: ``` $ cd vert.x $ java -jar ~/apps/meterian-cli.jar Meterian Client v0.1 - running locally: yes - interactive mode: on - working on folder: /tmp/vert.x Checking folder... Folder /tmp/vert.x contains a viable project! Authorizing the client... I cannot find a valid authorization token: I will open the browser so obtain one Please login as usual with your selected credentials Created new window in existing browser session. ``` As you can see the client introduced itself and then, as it's the first time it is launched, is opens a new browser window for you to login with your credentials and authorize it. After a successful login the client will proceed to collect the dependencies, using your local Maven installation (you can also move this task server side, but it's a good idea to execute this step on your local environment). After collecting the dependencies it will upload them to the Meterian servers, where they will be analysed. The client will also output information about the status of the process. ``` Client successfully authorized Loading build status... No build running found! Requesting build... Build allowed Running maven locally... - maven: loading dependency tree... - maven: dependencies generated... Execution successful! Uploading dependencies information - 63 found... Done! Starting build... Current status: in preparation Current status: "cleaning" - last updated at "2017-07-01T16:09:02.189" ``` When the work on the server is finished the client will emit the result of the analysis. The client will also output information about the status of the process, and provide you a link to access the report. ``` Final results: - report: "OK" - security: "0" - stability: "88" - timestamp: "2017-07-01 16:09:02" Full report available at: https://www.meterian.com/projects.html?pid=2fae2c4c-e22b-445c-a2cbcc7796d6c579&branch=master&login=true ``` Opening the link will force you through a login page: please make sure to use a set of credentials associated to your account to access, otherwise you will not be able to see the report. # Using the client in your CI/CD pipeline When you run the client as part of you CI/CD pipeline everything hopefully will be automated, and for that reason you want the client to work without the need of user intervention. You can achieve that using the non-interactive mode of the client that you can activate specifying the command line `--interactive=false` argument. In non-interactive mode the client will assume it's already authorized (see the details in the following section) and will fail if such authorization is missing. You will be able to control the exit code of the client using specific arguments, so that you can quickly block your pipeline if the libraries are not up to your required standards. In case you decide to do so, you can split the client work in two phases: the first one will just kick the analysis, returning the control to the calling shell so that you can run your build in parallel. At the end you can run the client again: it will collect the results from the server and report back accordingly # Authorization in non-interactive mode In order for the authorization to work in non-interactive mode you will need to generate a token on your [administrator page](https://www.meterian.com/account), then download and store it where you prefer on the local file system. When you will launch the client you will have to specify where the token is stored so that the client can authenticate in behalf of you, using the `--auth-file=/path-to-file` argument: as soon as the token is not revoked or deleted the client will be able to function without any interaction with the user and all the operation will be linked to your account. Another option is to simply set the environment variable METERIAN\_API\_TOKEN to the value of the token. In a Linux shell for example: \ `$> export METERIAN_API_TOKEN=12345678-90ab-cdef-1234-567890abcdef` \ When this variable is known Meterian will recognize the token and it will be able to proceed with the scan. # Providing the project branch In modern software development branches are widely used, and Meterian provides a report for each of them. If you use Git, the client usually detects automatically some basic information, including the current branch, but when this is not possible you can simply specify on the command line the parameter `--project-branch=name-of-your-branch` to enforce the branch name. A common scenario is when you are running within a CI system, which may not checkout the whole branch but just detach the head at a certain commit: please refer to the documentation of your CI system. You can also provide the project url (`--project-url`) and the current commit (`--project-commit`) if you want, but usually this information are automatically detected by the client. # Concurrent mode If you are running your build process on the same CI machine, sharing between different builds the same environment, you will need to run the client in concurrent mode using the command line parameter `--concurrent-mode`. In this mode the client will allow different builds to run concurrently on the same environment. Please note that in concurrent mode you cannot execute two phases builds # Two phases build Sometimes, especially if you run server side analysis, the process can take several minutes: in that situation you may want to start the process, go back to your build and collect the results later. This can be done passing the `--start-only` argument to the client. In that situation the client will collect the required data, send them to the server and return to the shell. You can then run your build, executing it in parallel to the work done on the Meterian servers. At the end of your build you just need to launch again the client with the same configuration, removing the `--start-only` argument: it will pick up the same analysis again, contact the server and return the results. Of course, if the server is still not ready, you may need to wait until everything is ready, but the client will report about the progress. In concurrent mode the two phases build will not work. # Controlling the exit code Specific arguments are at your disposal to control the exit code of the client based on the score, `--min-security` and `--min-stability` (plus `--min-licensing` if the feature is enabled on your account). These are the minimal scores: if not met, the build will have a positive exit code , which will be reported as a failure to the shell and will, most probably, stop your pipeline to progress. In case of error the code will be calculated using a bitmask over the exit code: +1 for a fail on the security score, +2 for a fail on the stability score, +4 for a fail on the licensing score. The default values for these scores are **90** for security and **80** for stability When any other error occurs, a negative exit code is produced, as described here:\ `-1 "No authorisation found"` \ `-2 "Failed to get authorisation via browser"` \ `-3 "Project unsupported"` \ `-6 "Analysis failed"` \ `-5 "A running build is present"` \ `-7 "Project URL was not specified"` \ `-8 "Error loading the configuration"` \ `-9 "Error communicating with cloud servers"` \ `-10 "Build tool not found"` \ `-12 "Plan limits exceeded"` \ `-13 "No analysis was run"` \ `-14 "Treoubleshooting failed"` \ `-15 "System unsupported"` **These exit codes above** can be silenced to 0 by specifying the parameter `--fail-gracefully` when launching the client. # Example: running the client in non-interactive mode Let's run the previous example, but now in non-interactive mode. First of all you will need to generate a token on the admin pages, download it and save it a well know location on the filesystem of the machine you intend to use. Let's assume you stored the token under `~/token.json`, the is available at `~/apps/meterian-cli.jar`, and your shell current working directory is the one of the project. You can now launch the client: ``` $ cd vert.x $ java -jar ~/apps/meterian-cli.jar --interactive=false \ --auth-file=~/token.json Meterian Client v0.1 - running locally: yes - interactive mode: off - working on folder: /tmp/vert.x [...] ``` The client will continue as usual, and if the token is valid it will proceed as in the interactive scenario. # General operations You will find in this chapter some general information about the client operation, which can be applied to both operational modes (interactive and non-interactive). # Running the analysis remotely The default operation mode of the client is running the dependency discovery locally, using the exact same environment used in your build. This is the default, and it's a very good idea as it forces the client to use the same environment, configuration and setup that the build tool (Maven, Gradle, etc.) is using for his own build. However it's possible to have this step executed remotely, on the Meterian servers, passing the `--local=false` argument to the client. In this situation the client will upload all your build files (build.xml, build.gradle, etc.) to the Meterian servers, as a necessary mean to compute your project's library dependencies. Please rest assured that such files will be stay on the server only for the time required for the computation and will be removed securely when no longer necessary. Please also note that: * remote scanning is possible only for Java and NodeJS * remote scanning is usually less precise than local scanning We generally suggest to use remote analysis unless specifically needed. # Interrupting the client The client stores the state of its progress in a hidden folder under your home, and can be interrupted at any time. When you are ready to resume it, you just need to launch it in the same folder and it will start exactly from the point where it was stopped. If you want to systematically exploit this behaviour to run the build in two separate stages please refer to chapter titled “Two phases build”. # Generating a report A console-based report is generated using the parameter `--report-console`: the system will try to adapt to the terminal capabilities, while it's possible to disable all ANSI escaping specifying `--report-console:nocolor`. An HTML report is generated on the file system using the parameter `--report-file=/path/to/file`. Please note that such file is just a “pointer” to the online report, so you will need internet access to view it using your browser. A JSON formatted report can also be generated, assuming your company is entitled to an “enterprise” plan. using the parameter `--report-json=/path/to/file`. A PDF formatted report can also be generated, assuming your company is entitled to an “enterprise” plan. using the parameter `--report-pdf=/path/to/file`. # Forcing or avoiding specific scans The current client will automatically select the correct set of scanners based on the content of your project folder. You can, however, force or disable a scanner using these parameters: * `--scan-java=false` will disable the Java scanner * `--scan-nodejs=false` will disable the NodeJS scanner * `--scan-javascript=true` will enable the Javascript/Web scanner (disabled by default) * `--scan-ruby=false` will disable the Ruby scanner * `--scan-dotnet=false` will disable the Dotnet scanner * `--scan-scala=false` will disable the Scala scanner * `--scan-php=false` will disable the PHP scanner A value of “true” will force the scanner to run (and fail if conditions are not met). # Excluding (and including) specific folders The standard behaviour for the Meterian client is to consider the folder where it's pointed to a project. It will look for any (supported) manifest files in such folder and will activate automatically the correct analysers. The inner folder structure is indeed opaque to the scanner, which relies on the declarations in the manifest files themselves. Some analyzers, however, can also work recursively, looking into subfolders of the current folder. This happens with Java/Ant, Dotnet, Golang, NodeJS and others. For that reason sometimes you may need to explicitly exclude or include folders, especially in complex projects. ### Excluding folders This behaviour can be controlled across all scanners that are using it providing a set of excluded folders that such analysers will not visit, using the parameter `--exclude-folders` as in this example, when we exclude all the "samples" folder/subfolders: ``` --exclude-folders=**/samples** ``` The `**` works across directories, while `*` is the general wildcard. \ These options allows to exclude multiple paths by separating them with a comma as in the example ``` --exclude-folders="**/foo**,**/baz**" ``` Please note that if no "glob" modifiers are used, then the system automatically translates into the above format, so that `--exclude-folders=foo` is equivalent to `--exclude-folders="**/foo**` **Note:** by default hidden folders are excluded, this behaviour is achieved by having the internal glob `***` set as the default value of the `--exclude-folders` flag. Should you want to retain this behaviour while adding your own glob patterns, simply add `***` following the usual comma. ### Including folders In the same way, it's also possible to include folders, which will take precedence above any exclusion: ``` --include-folders="**/src**,**/main**" ``` ### Glob modifiers These are known as "glob" patterns. This is how they are defined * **Wildcard characters:** * `*`: Matches any number of characters (including zero). * `?`: Matches exactly one character. * `[...]`: Matches any single character within the brackets. * `[!...]`: Matches any single character *not* within the brackets. * **Character classes:** * `[a-z]`: Matches any lowercase letter. * `[A-Z]`: Matches any uppercase letter. * `[0-9]`: Matches any digit. * `[:alpha:]`: Matches any alphabetic character. * `[:digit:]`: Matches any digit. * `[:alnum:]`: Matches any alphanumeric character. * `[:punct:]`: Matches any punctuation character. * `[:space:]`: Matches any whitespace character. * **Path separators:** * `/`: Used on Unix-like systems. * `\`: Used on Windows. * **Recursive matching:** * `**/`: Matches any number of directories. * **Internal:** * `***`: Matches hidden folders (whatever content within a top level hidden folder will be considered hidden as well; be it individual files or nested folders and their files) # Connecting through a proxy The client can work behind a proxy, which is a common situation in large enterprises. The client will read the standard variables “http\_proxy” or "https\_proxy" in order to detect such configuration automatically. The configuration however can also be done through these system properties (or [specific controls](/the-client/command-line-parameters/specific-controls)): `-Dhttp.proxy.host=`\ `-Dhttp.proxy.port=`\ `-Dhttp.proxy.user=`\ `-Dhttp.proxy.pass=` Both “host” and “port” properties need to be defined in order for the proxy to be used. When that happens, the client will echo to you that a proxy is being used while he tries to authorize itself, in a format similar to this one: ``` $ java -Dhttp.proxy.host=proxy.acme.org -Dhttp.proxy.port=3128 -jar ~/apps/meterian-cli.jar - Meterian Client v0.4.6 All rights reserved […] Authorizing the client... Using http proxy: http://proxy.acme.org:3128 […] ``` Furthermore, when you launch the client with the “--help” parameter it will also test the connectivity to the servers, as in this example: ``` $ java -jar ~/apps/meterian-cli.jar --help Meterian Client v1.2.6, build 09ce5de-283 All rights reserved --help Displays this help end exits(0) [...] Using http proxy http://proxy.acme.org:3128 Using authentication for proxy username:*** Meterian servers are reachable from this system ``` You also have a couple of fine grained controls over your http stack, which we honestly think will be rarely used but we list here as a matter of completeness, with their default: `-Dhttp.connect.timeout.millis=9000` The timeout in milliseconds to estabilish a connection over http/https `-Dhttp.socket.timeout.millis=8000` The timeout in milliseconds before declaring a connection over http/https dead. # System requirements The client is a Java native application written in Java8, so you will need to have a suitable JRE to run it. As it's written in Java it will run on any platform where a Java8 runtime is accessible. When using the [thin client](/the-client/client), the required tools will have to be installed and configured. This is not required when using the [dockerized client](/the-client/the-meterian-client-dockerized). Please refer to the [specific section regarding your language](/languages-support/languages-intro) for details. As the analysis on the dependencies is performed remotely, the client will need to have access to a working internet connection, capable of reaching directly using `https` the domain `*.meterian.com`. In case you need to use proxies, see the section connecting through a proxy. We plan to release the client also in form of a native application or a Python client: if you are interested in these development please contact our [support email](mailto:support@meterian.com) to get access to our early access program. # Command line parameters **`--help`**\ Displays a brief help page and exits (with code 0), like shown here:\ (please note that this is an example, your output may be different) ``` Meterian Client v1.2.24.4, build 13c1adb-730 © 2017-2022 Meterian Ltd - All rights reserved --tpn Displays the third party notice for this application and exits(0) --help Displays this help and exits(0) --clean Cleans any previous build information on the client --folder The root folder of the project (default: current folder) (example: --folder=/path/to/project) --local Runs this build using the local build system (default: --local=true) --interactive Allows the client to use the browser for interactive authentication (default: --interactive=true) --start-only Uses two-phase build, start remotely and exit (default: --start-only=false) --auth-file Uses an authorisation file (example: --auth-file=~/ci.json) --min-security Specifies the minimum security level to pass the build (default: --min-security=90 or as set in the account) --min-stability Specifies the minimum stability level to pass the build (default: --min-stability=80 or as set in the account) --min-licensing Specifies the minimum licensing level to pass the build (default: --min-licensing=95 or as set in the account) --report-file Produces an HTML report file (example: --report-file=~/report.html) --report-json Produces an JSON report file (example: --report-json=~/report.json) --report-junit Produces a JUNIT XML report file (example: --report-junit=~/report.xml) --report-pdf Produces an PDF report file (example: --report-pdf=~/report.pdf) --report-threadfix Produces an Threadfix-compatible report file (example: --report-threadfix=~/report.threadfix) --report-sbom Produces a Software Bill Of Meterials report file, format can be specified (see the doc) (example: --report-sbom=~/sbom.csv) --report-console Ouputs the scan report on the console (default: color if not specified - options color|nocolor|security|stability|licensing --project-url Specifies project url, if you are not using git (example: --project-url=https://svn.theforge.com/hubba/logos) --project-branch Specifies project branch, if you are not using git (example: --project-branch=master) --project-commit Specifies project commit, if you are not using git (example: --project-commit=9460cabbf623945495e6108c9d1979a9e7b5d8e7) --project-key Specifies project to associate this analysys to (example: --project-key=f6239454) --project-tags Allows to add a set of user defined Meterian tags (comme separated) to the project (example: --project-tags=production,platform) --concurrent-mode Enables concurrent mode (default: --concurrent-mode=true) --scan-java Forces java scan (default: will run if java code present) --scan-nodejs Forces nodejs scan (default: will run if nodejs code present) --scan-dotnet Forces dotnet scan (default: will run if dotnet code present) --scan-javascript Forces javascript scan (true:false:maybe) (default: won't run) --scan-ruby Forces ruby scan (default: will run if ruby code present) --scan-rust Forces rust scan (default: will run if rust code present) --scan-elixir Forces elixir scan (default: will run if rust code present) --scan-scala Forces scala scan (default: will run if scala code present) --scan-python Forces python scan (default: will run if python code present) --scan-perl Forces perl scan (default: will run if perl manifests present) --scan-golang Forces golang scan (default: will run if go manifests present) --scan-unity Forces scan of unity packages (true:false) (default: won't run) --scan-cpp Forces scan of C/CPP packages via conan (true:false) (default: will run if conan manifests are present) --scan-r Forces R scan (true:false) (default: will run if renv manifests present) --autofix Automatically fixes dependencies versions (see the online documentation) --dump Dumps the requested report on the console (example: --dump=dependencies) --process-notebooks Enables processing of (python only) jupyter notebooks --fail-gracefully The system will fail gracefully in case of network errors --exclude-folders Allow to excludes folder from analysis, where applicable (example: **/*.samples,**/*.labs)--exclude-folders=) --exclude-roots Allow to exclude root dependencies of choice from the analysis (example: --exclude-roots=app,lib) For any furher information please refer to the online documentation at docs.meterian.io Meterian servers are reachable from this system ``` It will also check that the connectivity with the Meterian cloud servers is in place: this is useful in case you want to validate your [proxy configuration](/the-client/general-operations/connecting-through-a-proxy) or you fear a corporate firewall is interfering. Please refer to the following subsections for further information. # General configuration **`--folder`**\ Specifies the root folder of the project.Please note that this option is not supported by the dockerized client yet. \ Default: the current folder \ Example: **`--folder=/projects/sample`** **`--auth-file`**\ Specifies where to find the authorisation file, which can be downloaded from the "Tokens" view of the Meterian Dashboard \ Example: **`--auth-file=~/ci.json`** **`--interactive`**\ When no authorisation file is present (or is invalid) and an authentication token is not present in the environment variables (see the section [authorisation in non-interactive mode](/the-client/using-client-ci-cd/autorization-in-non-interactive-mode) for more information) this option allows using the system standard internet browser in order to perform the authentication\ Default: true \ Example: **`--interactive=false`** **`--fail-gracefully`**\ In case of any system failure the client will report a non-zero exit code, thus failing or blocking the build if configured in a pipeline: this flag forces a 0 exit in case of a system failure\ Default: false \ Example: **`--fail-gracefully`**or **`--fail-gracefully=true`** **`--exclude-folders`**\ Certain scanners are able to work recursively: in that situation is possible to exclude folders from the analysis using standard global regexes separated by commas\ Example: **`--exclude-folders=**/*.samples,**/*.labs`** **`--ignore-exclusions`**\ Instruct the scanner to ignore all exclusions reported in the `.meterian` flle\ Default: false \ Example: **`--ignore-exclusions`** or **`--ignore-exclusions=true`** **`--exclude-roots`**\ In a multi project setting, should you need to exclude certain sub-projects you can use this flag to specify them\ Example: **`--exclude-roots=app,lib`** ``` Root project 'basic-multiproject' +--- Project ':android-sources' +--- Project ':app' \--- Project ':lib' ``` Given the above structure the example flag will cause project `app` and `lib` and all their sub-dependencies to be excluded from the analysis **`--external-exclusions`**\ Specifies where to load the `.meterian` exclusions file from instead of loaded it directly from within your project folder (read more about exclusions [here](/the-meterian-webapp/advanced-functionalities/set-exclusion))\ Example: **`--external-exclusions=/path/to/a/folder`** # Overriding scores Parameters used to control the score thresholds The client uses a default set of score thresholds in order to validate if an analysis is successful or not. Those thresholds can also be changed using the account dashboard, using the general configuration or a specific tag configuration. However, the client allows overriding such thresholds with command line parameters. **`--min-security`**\ Specifies the minimum security score to pass the build, overriding what's currently configured in the dashboard. \ Default: 90 or whatever is provided in the account \ Example: **`--min-security=97`** **`--min-stability`**\ Specifies the minimum stability score to pass the build, overriding what's currently configured in the dashboard. \ Default: 80 or whatever is provided in the account \ Example: **`--min-stability=97`** **`--min-licensing`**\ Specifies the minimum licensing score to pass the build, overriding what's currently configured in the dashboard. \ Default: 95 or whatever is provided in the account. \ Example: **`--min-stability=97`** # Overriding scopes Using a different scopes for the analysis For each of the section of the analysis (security, stability, licensing) the client can either analyze all the dependencies or only the ones that will be part of the production package, skipping the dependencies used in tests. This is normally configured in the dashboard, but the client can override those defaults: **--scopes=all** All scopes will be part of the analysis. **--scopes=prod** Only production scopes will be part of the analysis. # Producing reports Parameters used to produce reports The client can directly generate a few reports: these parameters are used to select which reports should be generated and, in some cases, what they should contain. **`--report-json`**\ Produces a JSON report file of the analysis (machine-readable)\ Example: **`--report-json=~/report.json`** **`--report-pdf`**\ Produces a PDF report file of the analysis (human-readable)\ Example: **`--report-pdf=~/report.pdf`** **`--report-junit`**\ Produces a Junit XML report file of the analysis (machine-readable)\ Example: **`--report-junit=~/report.xml`** **`--report-console`**\ Emits an analysis report on the console, a list of options separated by comma should be specified:\ \- color: enable colored output\ \- nocolor: disable colors and enhanced formatting (used on CI with bare-bone consoles)\ \- security: shows the security section\ \- stability; shows the stability section\ \- licensing: shows the licensing section \ Default: color if supported, includes all the sections\ Example: **`--report-console=nocolor,security,licensing`** **`--report-threadfix`**\ Produces a report file compatible with the Threadfix format. See [the specific section](/management-platforms/threadfix) for further details. **`--report-sbom`**\ Produces a SBOM report, the format is defined based on the extension of the file: * .json - a standard licensing bible report, JSON format * .pdf - a standard licensing bible report, PDF format * .csv - a standard SBOM Meterian report, CSV format * .cdx.xml - a standard CycloneDX SBOM report, XML format * .cdx.json - a standard CycloneDX SBOM report, JSON format Example: **`--report-sbom=sbom.cdx.xml`** It's also possible to request multiple reports, separating the file names with a comma. Example: **`--report-sbom=sbom.cdx.xml,bible.pdf`** **`--report-gitlab`**\ Produces a gitlab-compatible report to be used with [GitLab Ultimate](/devops-integrations/gitlab-ultimate)\ Example: **`--report-gitlab=gitlab.json`** **`--report-sarif`**\ Produces a SARIF report with the results from the analysis.\ Example: **`--report-sarif=report.sarif`** # Selecting scanners Parameters used to enable or disable scanners The client will generally automatically detect manifest files and select/activate scanners accordingly. However some scanners are not enabled by default and, sometimes, it may be preferable to run separate analysis with different scanners enabled in order to get different reports. These parameters provide the control required. **`--scan-java`** \ Controls if the Java scanner is run\ Default: Will run if a compatible manifest is present (see the [specific section](/languages-support/java) for further information)\ Example: **`--scan-java=false`** (to disable it) **`--scan-nodejs`** \ Controls if the NodeJS scanner is run\ Default: Will run if a compatible manifest is present (see the [specific section](/languages-support/nodejs) for further information)\ Example: **`--scan-nodejs=false`** (to disable it) **`--scan-dotnet`** \ Controls if the .NET scanner is run\ Default: Will run if a compatible manifest is present (see the [specific section](/languages-support/.net) for further information)\ Example: **`--scan-dotnet=false`** (to disable it) **`--scan-javascript`** \ Controls if the Vanilla Javascript scanner is run\ Default: Due to the fact that this scanner will potentially need to analyse any single file in the codebase, recursively, **it will NOT run unless requested.** (see the [specific section](/languages-support/vanilla) for further information)\ Example: **`--scan-javascript=true`** (to enable it) **`--scan-ruby`** \ Controls if the Ruby scanner is run\ Default: Will run if a compatible manifest is present (see the [specific section](/languages-support/ruby) for further information)\ Example: **`--scan-ruby=false`** (to disable it) **`--scan-rust`** \ Controls if the Rust scanner is run\ Default: Will run if a compatible manifest is present (see the [specific section](/languages-support/rust) for further information)\ Example: **`--scan-rust=false`** (to disable it) **`--scan-elixir`** \ Controls if the Elixir scanner is run\ Default: Will run if a compatible manifest is present (see the [specific section](/languages-support/elixir-erlang) for further information)\ Example: **`--scan-elixir=false`** (to disable it) **`--scan-scala`** \ Controls if the Scala scanner is run\ Default: Will run if a compatible manifest is present (see the the [specific section](/languages-support/java) for further information)\ Example: **`--scan-scala=false`** (to disable it) **`--scan-python`** \ Controls if the Python scanner is run\ Default: Will run if a compatible manifest is present (see the [specific section](/languages-support/python) for further information)\ Example: **`--scan-python=false`** (to disable it) **`--scan-perl`** \ Controls if the Perl scanner is run\ Default: Will run if a compatible manifest is present (see the [specific section](/languages-support/perl) for further information)\ Example: **`--scan-perl=false`** (to disable it) **`--scan-golang`** \ Controls if the Golang scanner is run\ Default: Will run if a compatible manifest is present (see the [specific section](/languages-support/golang) for further information)\ Example: **`--scan-golang=false`** (to disable it) **`--scan-cpp`** \ Controls if the C/C++ scanner is run\ Default: Will run if a compatible manifest is present (see the [specific section](/languages-support/c++) for further information)\ Example: **`--scan-cpp=false`** (to disable it) **`--scan-r`** \ Controls if the R scanner is run\ Default: Will run if a compatible manifest is present (see the [specific section](/languages-support/r) for further information)\ Example: **`--scan-r=false`** (to disable it) **`--scan-unity`** \ Controls if the Unity/.NET scanner is run\ Default: Due to the fact that the manifest files used by the Unity Package Manager are very similar to the ones used by other package managers, **it will NOT run unless requested.** (see the [specific section](/unity-packages) for further information)\ Example: **`--scan-unity=true`** (to enable it) **`--enabled-scanners`** \ Allows to activate only certain scanners by specifying a list of languages.\ Default: All scanners will be active during an analysis. It can be used in conjunction with the other options detailed here.\ Example: **`--enabled-scanners=swift,ruby,java`** (enables only swift, ruby and java) # Defining projects A set of parameters useful to override information about projetcs and to provide further control of specific details associated to projects and analysis. **`--project-url`**\ Allow to specify a project URL to associate to this analysis. Please note that this does not have to strictly be an URL, it's possible to use any name that's unique in your account.\ Default: It is automatically picked up using:\ \- the Git project URL, if available\ \- the SVN project URL, if available\ \- the project name from the manifest file\ \- the name of the root folder \ (please note, in this last case, that if you are using the Dockerized Client this will be always the default name "workspace", so you may end up stacking the different reports on the same project entry, which is not advisable)\ Examples:\ `--project-url=https://mysvn.com/myorg/myproject`\ `--project-url=almira/frontend` **`--project-branch`**\ Allow to specify a project branch to associate to this analysis. Analysis on different branches are kept segregated.\ Default: the Git project branch/tag, the SVN branch/tag, or the literal "head" if not available\ Example: `--project-branch=development` **`--project-commit`**\ Allow to specify a commit id to associate to this analysis. This is used just for reference.\ Default: the Git commit id if available or the SVN Revision if available\ Example: `--project-commit=5a8230597a8c4b999b278a63844c5238dacf51b6` **`--project-key`**\ A project key uniquely identifies a project on the system. A project key can be collected from the dashboard and specified via this parameter. In that situation, the analysis will be placed under the existing project. \ Example: `--project-key=15545f6c` **`--project-tags`**\ Allows to associate a set of tags to this project (comma separated). If not existent, the tag will be created on Meterian and associated to the project. Please note these tags do not usually represent a tag on your version control (i.e. git/svn), see the [specific section](/the-meterian-webapp/the-web-dashboard-1/tags) for any further detail.\ Example: `--project-tags=nocopyleft` # Advanced options Additional controls for specific mechanism **`--autofix`**\ Engages the autofix mechanism that, when supported, automatically updates the manifest files fixing problems detected during the analysis. See the [specific section ](/the-client/command-line-parameters/advanced-options/autofix)for further information. **`--process-notebooks`**\ Enables the processing of Jupyter Notebooks written in Python. See the [specific section](/jupyter-notebooks) for further information. **`--process-dlls`**\ Enables the processing of DLLs during a .NET scan. See the [specific section](/languages-support/.net/scanning-dlls) for further information. **`--debug`**\ Allows to run in debug mode, providing extensive log information that can be passed to the Meterian support when an intervention is required. **`--dump`**\ A generic information dump used for diagnostic purposes. Possible values:\ \- tree -> display a basic dependency tree\ \- dependencies -> display a basic list of dependencies\ Example: **`--dump=dependencies`** **`--use-ssl-certificates`**\ When connecting to HTTPS websites (or even when connected to a configured [proxy](/the-client/general-operations/connecting-through-a-proxy)) the client can use additional X509 certificates to operate, as long they are accessible from the file system.\ Example: **`--use-ssl-certificates=~/certs/local.pem,~/certs/qa.pem`**
# Autofix Through the autofix it is possible to have vulnerable and/or outdated dependencies definitions within a project's manifest file(s) automatically fixed. Fixes are applied by updating a given dependency version based on the chosen strategy and reach plus additional options. ### Supported manifest files * Gemfile/Gemfile.lock (Ruby) * composer.json/composer.lock (PHP) * pom.xml (Java/Maven) * \*.msproj (.Net) * package.json/package-lock.json/yarn.lock (NodeJs) * Pipfile/Pipfile.lock (python) ### Strategies * **safe**: update the dependency version number only with patch versions updates. This strategy is the least likely to introduce braking changes to your project. Patch version updates are used to apply backwards compatible bug fixes. * **conservative**: update the dependency version number with either minor or patch versions updates. This strategy could introduce breaking changes as, though backwards compatible, new features are introduced with minor version updates. * **aggressive**: update the dependency version number with either major, minor or patch versions updates. This strategy is the most likely to introduce breaking changes to your project. Major version updates make incompatible API changes. ### Reach * **all**: update all dependencies according to the chosen strategy * **vulns**: only update vulnerable dependencies according to the chosen strategy * **dated:** only update outdated dependencies according to the chosen strategy * **parent**: only update parent dependencies according to the chosen strategy ### Additional options * **no-overrides**: do not override dependencies (by default they are overridden) * **readonly**: only simulate fixes, do not apply them to actual manifest files ### Example usage You can instruct the client to perform the autofix with the `--autofix` flag. You can provide comma separated **programs** which are essentially a combination of preferred strategies, reaches and additional options aggregated with the **+** symbol. ``` --autofix:conservative+vulns,safe+dated+no-overrides ``` In this example the autofix will perform 2 programs consecutively. * \#1 program: vulnerable dependencies will be updated with either minor or patch version updates according to the safest versions available prioritising minor versions over patch versions. * \#2 program: all remaining outdated dependencies will be updated to the latest safest patch version without applying overrides. If only issuing `--autofix` to the client, the default programs ran are ``` safe+vulns,safe+dated+no-overrides ``` #### # Pull Requests Thanks to the avaiablility of [Autofix](/the-client/command-line-parameters/advanced-options/autofix), it's also possible to generate issues and pull-requests on Git repositories hosted on specific version control platforms. Check the links below to find out more: * [Meterian-pr documentation](https://github.com/MeterianHQ/meterian-pr/blob/main/README.md) * [Meterian GitHub action autofix workflow](https://github.com/MeterianHQ/meterian-github-action#autofix-workflow) # System information Getting information about the system **`--help`**\ The client displays a brief help page, then exits with code 0 **`--version`**\ The client displays the version of the client, then exits with code 0 **`--detect`**\ The client displays languages and tools detected, then exits with a specific code: \ \- 0 if the codebase is not supported\ \- 1 if the codebase is supported by at least one language\ \- 2 if the tooling supports autofix\ \- 3 if both previous conditions are true # Specific controls Allow in-depth configuration and control of the scanner engines. A set of control flags specific for each platform are available to further configure the client behaviour. These can be set in different ways: * using the Java thin client, specifying them via Java system properties, right after the "java" command, such as `java -Dparam1=value1, -Dparam2=value2 ...` * using the dockerized client using the CLIENT\_VM\_PARAMS environment properties:\ `export CLIENT_VM_PARAMS='-Dparam1=value1 -Dparam2=value2'` * in general with any client using the "--flags" operator, `... --flags:param1=value1,param2=value2`. A double comma can be used to escape a single comma contained in a value or parameter. So, for example, if you want to avoid to execute a "dotnet restore" when analysing a .NET project, you can do it either this way: ``` $ java -Ddotnet.restore=false -jar /tmp/meterian-cli.jar ``` Or this way, when for example using the dockerized client: ``` $ meterian-docker --flags:dotnet.restore=false ``` To check which control flags are available please refer to the following sections. # Maven specific controls This is a list of system flags that can be used to request specific Maven behaviours. Please refer to the parent section to learn how to specify them to the client. `maven.profile=` The profile that Maven will use while executing the scan. Please note that this will also cause an automatic change in the branch name, which will be now called branch-profile\_name `maven.binary=/path/to/mvn` Allows specifying the exact location of the Maven binary. It's not advisable however to use this property: please use the standard MAVEN\_HOME variable to specify where Maven is located. `maven.include.all=true` This will force the detection of all direct dependencies. Normally maven is asked for a dependency tree, and dependencies are collected only from such tree. If this flag is specified, all pom files will be examined to search any dependency not listed, such as, for example, internal dependencies used in plugins such as `jetty:run`which are not reported in the tree, as they are not in any application scope (those will be as a matter of fact listed with scope "`other`"). `maven.extra.parameters=-Dmaven.repo.local=/path/to/repo` This will allow to directly specify raw parameters that will be included in every maven command issued by the client. # Dotnet specific controls This is a list of system flags that can be used to request specific dotnet behaviours. Please refer to the parent section to learn how to specify them to the client. `dotnet.restore=false` Avoids the execution of the “dotnet restore” command during the analysis. `dotnet.tree.adjustment=true` Enable the tree recomputation on a multi project solution files. The tree will be revised so that the subtree of dependent sub-projects will be resolved within the tree of the parent component. `dll.exclude.folders="**/packages,**/obj"` Allows to specify a set of folders to be excluded from the [DLL scanner](/languages-support/.net/scanning-dlls), when activated. The example shows how to exclude the "packages" folder and the "obj" folder `dll.include.folders="**/libs"` Allows to specify a set of folders that must be included from the [DLL scanner](/languages-support/.net/scanning-dlls), when activated `dotnet.assets.ingest.runtimelibs=false` Avoid including runtime scoped libraries in the analysis. # Npm/Yarn specific controls This is a list of system flags that can be used to request specific NPM and YARN behaviours. Please refer to the parent section to learn how to specify them to the client. `npm.folders.excluded=samples,tests` During the scan of a NodeJS project, the client will usually look in all folders of the projects in order to detect any manifest file. if you want to avoid the client to look into specific subfolder you can use this flag. By default, the client won't look into folders named "lib", "examples", "samples" and of course "node\_modules". `npm.root.only=true` When false, directs the client to look only into the root folder and not in any subfolder for manifest files. By default the scanner will look also in subfolders. `npm.extra.parameters=--npm_config_allow_same_version` This will allow to directly specify raw parameters that will be included in every npm command issued by the client. `npm.ls.enabled=true` This controls the usage of the "npm ls" command to obtain the list of dependencies and solely relies on the content of the package.lock. When set to `false`, you should make sure your lock files are present and up to date. `nodejs.workspaces.enabled=false` When false the client is instructed to avoid processing the current project folder as the top level folder for either [pnpm workspaces](https://pnpm.io/pnpm-workspace_yaml), [yarn workspaces](https://classic.yarnpkg.com/lang/en/docs/workspaces/) or [npm workspaces](https://docs.npmjs.com/cli/v7/using-npm/workspaces). # Gradle specific controls This is a list of system flags that can be used to request specific Gradle behaviours. Please refer to the parent section to learn how to specify them to the client. `gradle.root.only=false` When true, forces the scanner to recursively traverse the directory path, analysing all Gradle projects present. By default, the client looks only in the root folder. `gradle.kts.dependency.set=dependencies` When using Gradle powered by Kotlin, it may be required to tell the scanner which configuration of dependencies it should take under consideration. For example, for an Android application, the value of such variable will be usually "`app.dependencies`" rather than the default value "`dependencies`". `gradle.configurations=implementation,test,release` When used, it allows to select which gradle configuration should be taken in account when executing the analysis. By default, all configurations are taken in account. # Ant/Ivy specific controls `ant.extra.parameters=dev` This will allow to directly specify raw parameters that will be included in every maven command issued by the client. `ant.build.file=` This will allow you to override the default build file used during the Ant dependency generation. The default build file is build.xml. `ant.ivy.build.file=` This will allow you to override the default build file used during the Ivy dependency generation. The default build file is build.xml. # The Dockerized Client Scan for vulnerabilities in your project using the Meterian Client packaged as a Docker image. You can do this *without having to install any dependencies needed for the Meterian Scanner client to run*, and the scan happens in an isolated environment, inside the Docker container. This docker image contains the Java runtime plus all the required tools for the full range of platforms supported by the Meterian platform. Download the latest version of the Dockerized client by simply typing the following in your terminal ``` docker pull meterian/cli:latest ``` Alternatively, if you wish you can download a lighter platform-specific variant of the image ``` docker pull meterian/cli:latest-java ``` There are as many variants as the [languages we support](https://docs.meterian.io/containers-support/the-meterian-client-dockerized/supported-languages). Visit the [DockerHub repository](https://hub.docker.com/r/meterian/cli) for further information on additional variants and versions. # Basic usage First of all, [install Docker](https://docs.docker.com/install/linux/docker-ce/ubuntu/#install-using-the-convenience-script) on the host machine. The easiest way to use the dockerized Meterian Client is via the script [meterian-docker](https://github.com/MeterianHQ/meterian-scanner-docker/blob/master/scripts). It accepts all [the standard parameters](/the-client/command-line-parameters) exactly in the same way, but it cannot be used in interactive mode, therefore you will need to provide it with [a valid token](https://www.meterian.com/account/#tokens) using the environment variable `METERIAN_API_TOKEN`. We suggest you populate such variable in your startup script. Assuming you put the script in your path, just **move in the folder of your project** and type: ``` meterian-docker [Meterian CLI Options] ``` Alternatively you can set the environment variable `METERIAN_WORKDIR` with the path to your project folder and run the convenience script: ``` export METERIAN_WORKDIR=/project-folder meterian-docker ``` Everything will work exactly like a normal invocation of the client. Please note that, by default, the script binds into the container the standard library cache folders used by the package managers (see the table below for the ones that we bind), so that the execution is as fast as it was running on your machine. If you really want you can avoid this by adding `--unbound` to your command line arguments. | Package Manager | Folder | | --------------- | ------------------------------- | | \* |

~~/.cache
~~/.local

| | maven | \~/.m2 | | dotnet |

~~/.dotnet
~~/.nuget

| | ruby | $(gem environment gemdir)/cache | | node | /usr/lib/node\_modules | | gradle | \~/.gradle | | sbt |

~~/.sbt
~~/.ivy2

| An additional option to note when using the [meterian-docker](https://github.com/MeterianHQ/meterian-scanner-docker/blob/master/scripts) script is `--image:` . By default the scripts uses the `latest` tag, but providing this option instructs it to use a [given tag](https://hub.docker.com/repository/docker/meterian/cli/tags) of the `meterian/cli` image. ``` meterian-docker --image:latest-python ``` The above example will cause the script to use the `meterian/cli:latest-python` image: we also provide [platform-specific images](https://hub.docker.com/r/meterian/cli/tags) should you not wish to use the full version to save bandwidth or space, as the "generic" image ("latest") contains all the tooling supported. # Advanced usage Learn how to: * Invoke the client directly [via docker](/the-client/the-meterian-client-dockerized/advanced-usage/invoking-via-docker) * Use a [platform-specific image](/the-client/the-meterian-client-dockerized/advanced-usage/platform-specific-image-usage) * Use it on a [CI/CD platform](/the-client/the-meterian-client-dockerized/advanced-usage/usage-on-a-ci-cd-platform) * [Disable the client auto-update mechanism](/the-client/the-meterian-client-dockerized/advanced-usage/disable-the-client-auto-update) # Invoking via Docker If you want to run docker explicitly you can, of course, do that as well. The basic way to run the container is this one: ``` PWD=your-project-folder docker run -it --rm \ --volume ${PWD}:/workspace \ --env METERIAN_API_TOKEN=your-token-here \ meterian/cli [Meterian CLI Options] ``` Please note that in this situation the local caches used by the tools will not be bound. We suggest you bind those folders, and the easiest way to do that is to use the provided [meterian-docker](https://github.com/MeterianHQ/meterian-scanner-docker/blob/master/scripts) script. However, if you feel adventurous, you can of course do it yourself. For example, to bind the java caches in a maven build: ``` PWD=your-project-folder docker run -it --rm \ --volume ${PWD}:/workspace \ --env METERIAN_API_TOKEN=your-token-here \ --mount type=bind,source=${HOME}/.m2,target=/home/meterian/.m2 \ meterian/cli [Meterian CLI Options] ``` In some cases (i.e dotnet) you will need to specify the `UID` and the `GID` in order for the system to work, reaching something like this: ``` PWD=your-project-folder HOST_UID=`id -u` HOST_GID=`id -g` docker run -it --rm \ --volume ${PWD}:/workspace \ --env METERIAN_API_TOKEN=your-token-here \ --mount type=bind,source=${HOME}/.dotnet,target=/home/meterian/.dotnet \ --mount type=bind,source=${HOME}/.nuget,target=/home/meterian/.nuget \ --env HOST_UID=${HOST_UID} \ --env HOST_UID=${HOST_GID} \ meterian/cli [Meterian CLI Options] ``` The script is run by the `meterian` user in the container, with their home at `/home/meterian`. You can see how this works in the source of the [meterian-docker](https://github.com/MeterianHQ/meterian-scanner-docker/blob/master/scripts/meterian-docker) script. Please get in touch if you have any issue using the [support channels](mailto:support@meterian.com). # Platform-specific images In addition to the full Dockerized client image containing all dependencies needed by all the supported programming languages, we also provide platform-specific images for targeted scans. The latter are lighter as they are optimised for an individual platform. All the code snippets provided prior to this section just require a slight edit to support the given variant of the image you are using ``` PWD=your-project-folder docker run -it --rm \ --volume ${PWD}:/workspace \ --env METERIAN_API_TOKEN=your-token-here \ meterian/cli:1.1.5-go [Meterian CLI Options] ``` Note how only the target image has changed from `meterian/cli` to `meterian/cli:1.1.5-go` which is a very specific version. The same target image edit can also be applied to the handy `meterian-docker` script mentioned in the [Basic usage section](https://docs.meterian.io/containers-support/the-meterian-client-dockerized/basic-usage). Simply edit the `VERSION` variable within the script to point to the desired version ``` ... VERSION="1.1.5-go" DOCKER_FULL_IMAGE_NAME="meterian/cli:${VERSION}" ... ``` # Usage on a CI/CD platform The dockerized client can be used directly on a CI/CD platform. The easiest way is usually via the via the script [meterian-docker-ci](https://github.com/MeterianHQ/meterian-scanner-docker/blob/master/scripts). However, depending on the platform used, some base images may already be present. In that situation, we suggest taking a look at the specific instructions in the [CI Server Integrations section](/ci-server-integrations/introduction). # Disable the client auto-update The Dockerized client is built with the latest version of the client available at build time which then remains unchanged within the relative image. To ensure that users are always using the most up to date version of the Meterian client, this is auto-updated by default when a more recent version is detected. To disable this behaviour you can use the `CLIENT_AUTO_UPDATE` environment variable ``` export CLIENT_AUTO_UPDATE=false ``` # Troubleshooting We track here solutions to issues we troubleshoot. Please view the subpages for topic-specific content. # Client auto update failure By default the Dockerized client is set up to automatically update the Meterian client it is built with. As such the latest version of the client is downloaded and cached right before the scan. Should this operation fail the following error is printed ``` $ meterian-docker Updating the client... Unexpected error: client update failed via url: https://www.meterian.io/downloads/meterian-cli.jar Please ensure connections to https://www.meterian.io/downloads/meterian-cli.jar are permitted from the Docker container ``` As per error message you should ensure connections to the download URL is functioning on your end. Should this not be enough, to further diagnose what is causing the `curl` call to fail you can run this command ``` $ docker run --rm -it --entrypoint "/usr/bin/env" meterian/cli curl "https://www.meterian.io/downloads/meterian-cli.jar" ``` # Docker specifics After installing Docker, if you are using a Linux distribution you may want to ensure that you can use it as non-root user by running this command: ``` $ sudo setfacl --modify user::rw /var/run/docker.sock ``` # How scores work Meterian’s assessment report displays three scores labelled Security, Stability and Licensing. All these scores range from 100 to 0, where 100 is the best score. Scores represent a straightforward way to understand the posture of a codebase and can be used to[ control the exit code](/the-client/using-client-ci-cd/controlling-the-exit-code) of the scanner in order to fail a build on a CI system. **Security** measures how likely is a codebase to be affected by security vulnerabilities. A value of 0 stands for “very likely to be insecure”, while a value of 100 is, of course, very secure according to our analysis. There are two basic algorithms used to compute this score, that can be selected in the [dashboard configuration](/the-meterian-webapp/the-web-dashboard-1/configuration). **Stability** shows how likely is code to be subject to critical defects. While not directly related to software security, critical defects can cause the application to misbehave, crash, or perform poorly. The Stability indicator is calculated taking in account all components that can be patched: each missing patch will deduct 1 point from the initial 100 score. **Licensing** measures how likely is code compliant to the [policies](/the-meterian-webapp/the-web-dashboard-1/policies) defined at the account level in regards to the licenses of the components. Each component that does not declare a license will deduct one point from the initial 100 score, and any component with a license forbidden by the applicable polices will immediately bring the score to 0 Enterprise customers can request to use custom algorithms to compute those scores. Some may think our scoring applies a harsh judgement. But isn’t it better to receive a stronger alert to call attention to bolster your code’s security rather than risk a more mild alert that could lead to undeserved complacency? So please don’t be intimidated by seeing Security or Stability scores of 0! Make haste to fix the problems repo # Guide: your first scan! How to execute your first scan using Meterian In the following section we briefly explain you how to do your first scan in different environment and using different tools. Please do not hesitate to [ask support](mailto:support@meterian.io) if you need help! * [Your first scan with the Java Thin Client](/the-client/guide-your-first-scan/your-first-scan-java-thin-client)\ Runs on your local machine, you need to have Java installed and your development tools * [Your first scan with the Dockerized Client](/the-client/guide-your-first-scan/your-first-scan-dockerized-client)\ Runs on your local machine, you need to have Docker installed * [Your first scan with a GitHub action](/the-client/guide-your-first-scan/your-first-scan-github-action)\ Runs on GitHub using our GitHub action, nothing to install, quick setup # Your first scan (java thin client) How to use the dockerized client to execute your first scan The thin client requires a [Java Runtime Environment](https://www.java.com/) 1.8+ to run and does not include any standard SDK that is usually needed to produce the dependencies graph of your application. For example, if you want to analyse a Java project based on Maven, then Maven will have to be installed on your machine. The same happens if you want to analyse a .NET project: the .NET SDK will have to be installed and correctly configured on the machine you are running the client from. We expect developers to have their tools on their machines :) but in case they do not, please prefer using the[ dockerized version of the client](/the-client/guide-your-first-scan/your-first-scan-dockerized-client), which includes also all the necessary tools. This guide assumes you are working on a \*nix environment: if you are using windows, please refer to the page ["Use the thin client on Windows"](/the-client/client/use-the-thin-client-on-windows). **1. download the Java Thin Client from the Meterian cloud** ``` curl https://www.meterian.io/downloads/meterian-cli.jar > ~/meterian-cli.jar ``` **2. set up the METERIAN\_API\_TOKEN environment variable with one of** [**tokens available in the account**](https://www.meterian.com/dashboard#tokens)**,** or create a new one. We also suggest you add this to your [.bashrc](https://www.journaldev.com/41479/bashrc-file-in-linux) ``` export METERIAN_API_TOKEN=your-token-uuid-here ``` **3. launch the client once to validate everything is working properly** \ (note: the first time the thin client may also be downloaded) ``` java -jar ~/meterian-cli.jar --version Meterian Client v1.2.24.5, build 51bcad7-764 ``` **4. move into the folder you have your codebase and execute the client** ``` java -jar ~/meterian-cli.jar © 2017-2022 Meterian Ltd - dockerized version 2.3.53.699 Meterian Client v1.2.24.5, build 51bcad7-764 © 2017-2022 Meterian Ltd - All rights reserved System information: - running locally: yes - interactive mode: off - working on folder: /home/john/projects/zxing - autofix mode: off Checking folder... Folder /workspace contains a viable project! Authorizing the client... Client successfully authorized Account: "Acme Team Account" - Minimum scores: - security: 90 - stability: 90 - licensing: 90 - Analysis scopes: - security: packaged components - stability: all components - licensing: all components Project information: - url: https://github.com/zxing/zxing - branch: local - commit: 708b14bef82a087dd0fefbada81398dd2100366c Java scan - running maven locally... - maven: loading dependency tree... - maven: loading dependency tree (alternate)... - maven: dependencies generated... Execution successful! Uploading dependencies information - 23 found... Done! Starting build... Current build status: initialized - the project has been classified as opensource Current build status: in preparation Current build status: process advices at 2022-06-13T15:41:33.660 Final results: - security: 85 (minimum: 90) - stability: 98 (minimum: 90) - licensing: 100 (minimum: 90) Full report available at: https://www.meterian.com/projects/?pid=...&branch=local&mode=eli Build unsuccessful! Failed checks: [security] ``` All done! You can click on the link and see the final report in HTML. you can also ask the system to generate, for example, a console report adding to the command "`--console-report`" to see immediately all the information. To learn more about it, see the section "[Command line parameters](/the-client/command-line-parameters)". You can also setup a simple script that will automatically update your client if required: ```bash #!/bin/sh curl -s -o "~/meterian-cli.jar" -z "~/meterian-cli.jar" "https://www.meterian.io/downloads/meterian-cli.jar" >/dev/null java -jar ~/meterian-cli.jar $* ``` # Your first scan (dockerized client) How to use the dockerized client to execute your first scan The Dockerized Client requires your environment to have docker support: everything else is provided in the docker image, as it contains the Java runtime plus all the required tools for the full range of platforms supported by the Meterian platform. This guide assumes you are working on a \*nix environment: if you are using windows, docker may work slightly differently. Please refer to the page ["Use the thin client on Windows"](/the-client/client/use-the-thin-client-on-windows). **1. pull the docker scanner official image** ``` $ docker pull meterian/cli:latest ``` **2. download the simplified script to run the docker image and make it executable** ``` $ curl https://raw.githubusercontent.com/MeterianHQ/meterian-scanner-docker/master/scripts/meterian-docker > ~/meterian; chmod +x ~/meterian ``` **3. set up the METERIAN\_API\_TOKEN environment variable with one of** [**tokens available in the account**](https://www.meterian.com/dashboard#tokens)**,** or create a new one. We also suggest you add this to your [.bashrc](https://www.journaldev.com/41479/bashrc-file-in-linux) ``` export METERIAN_API_TOKEN=your-token-uuid-here ``` **4. launch the client once to validate everything is working properly** \ (note: the first time the thin client may also be downloaded) ``` $ ~/meterian --version Meterian Client v1.2.24.5, build 51bcad7-764 © 2017-2022 Meterian Ltd - dockerized version 2.3.53.699s ``` **5. move into the folder you have your codebase and execute the client** ``` $ ~/meterian © 2017-2022 Meterian Ltd - dockerized version 2.3.53.699 Meterian Client v1.2.24.5, build 51bcad7-764 © 2017-2022 Meterian Ltd - All rights reserved System information: - running locally: yes - interactive mode: off - working on folder: /workspace - autofix mode: off Checking folder... Folder /workspace contains a viable project! Authorizing the client... Client successfully authorized Account: "Acme Team Account" - Minimum scores: - security: 90 - stability: 90 - licensing: 90 - Analysis scopes: - security: packaged components - stability: all components - licensing: all components Project information: - url: https://github.com/zxing/zxing - branch: local - commit: 708b14bef82a087dd0fefbada81398dd2100366c Java scan - running maven locally... - maven: loading dependency tree... - maven: loading dependency tree (alternate)... - maven: dependencies generated... Execution successful! Uploading dependencies information - 23 found... Done! Starting build... Current build status: initialized - the project has been classified as opensource Current build status: in preparation Current build status: process advices at 2022-06-13T15:41:33.660 Final results: - security: 85 (minimum: 90) - stability: 98 (minimum: 90) - licensing: 100 (minimum: 90) Full report available at: https://www.meterian.com/projects/?pid=...&branch=local&mode=eli Build unsuccessful! Failed checks: [security] ``` All done! You can click on the link and see the final report in HTML. you can also ask the system to generate, for example, a console report adding to the command "`--console-report`" to see immediately all the information. To learn more about it, see the section "[Command line parameters](/the-client/command-line-parameters)". # Your first scan (GitHub Action) Similarly to the Dockerized client and all our CI/CD pipelines integrations, the [Meterian GitHub Action](https://github.com/marketplace/actions/meterian-scanner) includes all the necessary tools required to perform scans for project developed across all the languages we support. Essentially all you need to worry about is how to set it up for usage. **Open source project repository** Commit the following YAML workflow configuration file to your repository in the folder `.github/workflows` ```yaml # .github/workflows/main.yml name: Meterian Scanner workflow on: push jobs: meterian_scan: name: Meterian client scan runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v3 - name: Meterian Scanner uses: MeterianHQ/meterian-github-action@v1.0.17 with: oss: true ``` **Note**: performing an open source scan with this configuration will generate a public report on the default account. To have the resulting report in your personal account provide your personal token to the configuration as explained below\.- **Private project repository** First of all, generate a Meterian API token: * Log into your account on [https://meterian.com](https://meterian.com/) * Create an new API token from the dashboard Then Add the above token as a GitHub secret by the name `METERIAN_API_TOKEN` * In your repository navigate to the Secrets page ( `Your repository > Settings > Secrets` ) * Click on the `Add a new Secret` Then commit this YAML workflow configuration file to your repository in the folder `.github/workflows` ```yaml # .github/workflows/main.yml name: Meterian Scanner workflow on: push jobs: meterian_scan: name: Meterian client scan runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v3 - name: Meterian Scanner uses: MeterianHQ/meterian-github-action@v1.0.17 env: METERIAN_API_TOKEN: ${{ secrets.METERIAN_API_TOKEN }} ``` Committing these action workflow configurations will trigger your first workflow run which is visible on GitHub in the Actions tab of your repository
Note these workflows are triggered on push, should you wish to change this behaviour for your repository consult the detailed workflow syntax documentation [here](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on). The parameters for the action configuration are listed in the [action documentation page on GitHub](https://github.com/marketplace/actions/meterian-scanner). You can find a live example using our action [here](https://github.com/MeterianHQ/spark), and a list of working examples for all the supported languages can be found [here](https://github.com/marketplace/actions/meterian-scanner#examples). If your workflow run is not triggered as expected ensure you have GitHub Actions enabled in your repository by reviewing the Actions Permissions in the Actions/General page of your repository settings. # Scan behaviour matrix The scanner works using a plugin architecture, so each scanner plugin have different capabilities and requirements. However, there are conditions that need to be met in order to any scanner plugin to work correctly. Considering the following condition:
ConditionExplanation
LanguageThe language implemented by the plugin
Build ToolThe build tool used in the codebase
Valid build required?Do we need the build to execute and complete successfully?
Tool required?Do we need to execute the build tool installed?
Invalid dependency?What happens if the project includes an invalid/unreachable dependency?
These are the level of support provided and the corresponding behaviour of the scanner | Language | Build Tool | Valid build required? | Tool required? | Invalid dependency? | | ----------------------------------------------------------------------------------- | ------------ | --------------------- | ------------------ | ------------------- | | [C/C++](https://docs.meterian.io/languages-support/c++) | conan | No (with lockfile) | No | Complete | | [Clojure](https://docs.meterian.io/languages-support/clojure) | lein | No | Yes | Complete | | [Clojure](https://docs.meterian.io/languages-support/clojure) | clojure | No | Yes | Complete | | [Dart/Flutter](https://docs.meterian.io/languages-support/dart-flutter) | dart | No (with lockfile) | No (with lockfile) | Complete | | [Elixir](https://docs.meterian.io/languages-support/elixir-erlang) | mix | No (with lockfile) | No (with lockfile) | Complete | | [Golang](https://docs.meterian.io/languages-support/golang) | go | Yes | Yes | Failure | | [Java](https://docs.meterian.io/languages-support/java) | gradle | Yes | Yes | Complete | | [Java](https://docs.meterian.io/languages-support/java) | mvn | Yes | Yes | Complete | | [Java](https://docs.meterian.io/languages-support/java) | ant (+ivy) | No | No | Complete | | [Scala](https://docs.meterian.io/languages-support/java) | sbt | Yes | Yes | Failure | | [.NET](https://docs.meterian.io/languages-support/.net) | dotnet | Yes | Yes | Complete | | [.NET](https://docs.meterian.io/languages-support/.net) | paket | No | No (with lockfile) | Complete | | [NodeJS](https://docs.meterian.io/languages-support/nodejs) | npm | No (with lockfile) | No (with lockfile) | Complete | | [NodeJS](https://docs.meterian.io/languages-support/nodejs) | pnpm | No (with lockfile) | No (with lockfile) | Complete | | [NodeJS](https://docs.meterian.io/languages-support/nodejs) | yarn | No (with lockfile) | No (with lockfile) | Complete | | [Perl](https://docs.meterian.io/languages-support/perl) | carton | No (with lockfile) | No (with lockfile) | Complete | | [PHP](https://docs.meterian.io/languages-support/php) | composer | No (with lockfile) | No (with lockfile) | Complete | | [Python](https://docs.meterian.io/languages-support/python) | pipenv | No (with lockfile) | No (with lockfile) | Complete | | [Python](https://docs.meterian.io/languages-support/python) | poetry | No (with lockfile) | No (with lockfile) | Complete | | [Python](https://docs.meterian.io/languages-support/python) | requirements | No | Yes | Complete | | [R](https://docs.meterian.io/languages-support/r) | R | No (with lockfile) | No (with lockfile) | Complete | | [Ruby](https://docs.meterian.io/languages-support/ruby) | bundle | Yes | Yes | Complete | | [Rust](https://docs.meterian.io/languages-support/rust) | cargo | No (with lockfile) | No (with lockfile) | Complete | | [Swift / Objective-C](https://docs.meterian.io/languages-support/swift-objective-c) | cocoapods | No (with lockfile) | Yes | Failure | | [Swift / Objective-C](https://docs.meterian.io/languages-support/swift-objective-c) | SwiftPm | No (with lockfile) | No (with lockfile) | Failure | | [VanillaJS](https://docs.meterian.io/languages-support/vanilla) | none | No | No | Complete | # Accessing your account How your user gets allocated to an account In order to access the platform you need a successful login via any of the login mechanisms: social logins, credentials, [Single-](/master/sso-and-mfa)[Sign-On](/master/sso-and-mfa). **The platform identifies you with your full email,** collected via the login. An email may belong to one account only. If your email was previously added to an account, either as a direct member or as part of a [team](/the-meterian-webapp/the-web-dashboard-1/teams), then you are simply part of that account. If nobody added you to an account, there are automatic provisioning systems kicking in: * you may be automatically added to an account on your **email domain** [(see here)](/the-meterian-webapp/advanced-functionalities/auto-grouping/organization-autogrouping) * you may be automatically added to an account based on your **GitHub organisation** [(see here)](/the-meterian-webapp/advanced-functionalities/auto-grouping/how-to-set-an-organization) Please note that these mechanisms may not be enabled on your instance or on your account: in that case the system will simply deny access access until your email is added as a direct member of a team or of an account. # The Web Dashboard In this section you will find a brief description of the Web Dashboard: * [Projects](/the-meterian-webapp/the-web-dashboard-1/projects) * [Insights](/the-meterian-webapp/the-web-dashboard-1/insights) * [Tokens](/the-meterian-webapp/the-web-dashboard-1/tokens) * [Badges](/the-meterian-webapp/the-web-dashboard-1/badges) * [Policies](/the-meterian-webapp/the-web-dashboard-1/policies) * [Tags](/the-meterian-webapp/the-web-dashboard-1/tags) * [Teams](/the-meterian-webapp/the-web-dashboard-1/teams) * [Configuration](/the-meterian-webapp/the-web-dashboard-1/configuration) # Projects This view shows all the project analyzed from the various scanners connected to this account and the related reports. ![](https://lh4.googleusercontent.com/sZsf2DOlU5vf4r86dpruge3GsElCoiKY86JIQ24wPE3u6qWW-OroI2zysEF558ZLPo73YOuGeIqNs7-Pm8lUpi-Avvk1w0ltnaGjh4jSYXDqC7zLTrS7Np1JTdZ4tF-mVIYkntXT) # Insights Here you can view all the components with issues discovered during the analyses from the various scanners. Using sorting and filtering allows you to detect the most problematic components so that you can prioritize your actions. ![](https://lh4.googleusercontent.com/g4BzFjLFB4_XYGl8F-5_cP4CDpZM6hLTBIPrxD-Shl9sMVx0YK1SC3IW-kpauypeZlY2rOCz2CEq1lW8rAd5K_N6lpMcWiYSnDsvLtwK6wlfm3CV-pbHrR4I1YU210e6-WXcYtpI) it's possible to consult the detail of a component to do a deep dive into the issues such as vulnerabilities or licenses outside policies. You will also be able to see if new versions that solve such problems are available, and the full list of projects using the component. ![](https://lh6.googleusercontent.com/Pse6nSl8r2Xi7BoGDDVtaMorIt-liJuze192q2wNNOmJSmKonoAnGINfUbFwBfFy1k5ijBxODxRYRtE_jgVecA4LGrGLB2y4ZIHAVhotbvsm4lR_xrwZvkOIcFv9lNbPBT52PJzu) # Tokens This page allows you to define authentication tokens that can be later used to call APIs or \ use the various clients (thin client, dockerized client, container scanner, etc..).
You can setup a token with an expiration (which is recommended) or not. At any point in time you can revoke the token so that it won't be usable anymore. It's a good policy to assign tokens to each different consumer. # Badges In the badges section, it's possible to generate simple dynamic labels that can then be added in its own GitHub project, to publish the state of vulnerabilities and licenses, like in this example: ![](https://lh5.googleusercontent.com/Xw3pCsw89XzzkReqtUNM6Zye_J4C7C3frlld67W41Or1j-4EdUviYFkEAAm_6POcP6-x3rYI2UNv-5jziP-bsFPOvtqjNcw7n5UH8t-NRvBaF57nt-kqU1Raq5M04VSJX2W2x0wY) Badges can be used on public and private projects on GitHub. See the [Badges](/badges/gh-intro) section for more information. # Policies In the Policies section is possible to create, modify or delete the policies related to the licenses of opensource components. Every policy can be associated with a set of projects using regular expressions or tags. Every rule defines the licenses that are/are not allowed. The standard used is the SPDX, but specific extensions are provided for some proprietary licenses and specific licenses for some software producers. ![The policies screen](/files/KsLUeINvQVhvRLUt3iUC) The system already provides pre-compiled templates to manage some common cases: * exclusion of all Copyleft licenses * exclusions of all Affero licenses * exclusions of all GPL licenses ## Structure of a policy A policy contains a list of licenses, and can be of two different types: * DENY: it will deny all licenses listed in the policy * ALLOW: it will allow **only** the policies listed in the policy All policies applicable to a project, based on tag or on matching, will be computed together. In case of a violation, the pollcy will be clearly indicated in the report:
# Tags Tags are labels that can be associated with various items. They can be used to: * semantically group projects together * link projects to license policies, if a project and the policy have the same tag then the policy is automatically enforced on the project. * enforce a different level of thresholds for security/stability/licensing in the analysis ![The Tags view](/files/MqVrbSKQGMeknRvTMAu6) While tags can be applied on the [Projects](/the-meterian-webapp/the-web-dashboard-1/projects) and [Policies](/the-meterian-webapp/the-web-dashboard-1/policies) view, a special "Tags" view is available in order to manage those in one single place. ![Configuring a single tag](/files/UGTcIEeDk9hSlHVe6VHz) # Teams In this page you can manage the teams in your account. You can locate a default team called "Everyone" that groups every single user in the account. ### Create teams To create a team simply add their name in their description from the left-hand side panel and click the "Add" button. ![](/files/FSFxYsPHAw63jd0TGeLd) ### Add members to a team To add a member to a team simply select the team to work on first, and then from the "Add a new member" section of the page right next to the teams panel add their details and click the button "Add". ![](/files/dkxgI557hcJbQfju66aK) # Configuration In this section, available only to the account admins, it's possible to configure various aspects of the platform, such as the minimum acceptable scores or the scopes to use in the analysis.
#### **Security score calculation** Here you can select the security score calculation algorithm, between the two available:
selection of the security score calculation algorithm
* **by CVSS**: the score starts at 100. For each vulnerability, points are deducted based on its CVSS score. The amount of points deducted is between 0 and 50: it's proportionate to the score of the vulnerability, which goes from 0 to 10. For example, a score of 9 will deduct 45 points, while a 1 will deduct 5 points. A suggestion will always deduct 0.25. * **by Severity**: The score starts at 100, then each SUGGESTION deducts 0.25, each LOW deducts 5, each MEDIUM deducts 10, each HIGH deducts 20, each CRITICAL deducts 25. The minimum score is 0
You can also select the default thresholds used to qualify an analysis as a PASS or a FAIL. These thresholds can also be changed using [Tags](/the-meterian-webapp/the-web-dashboard-1/tags) or passing the specific parameters to the client used in the analysis (see the specific details in the documentation of the client used).
#### **Security Thresholds** Here you can select thresholds for your security alerts: vulnerabilities that are not reaching the thresholds will be automatically mitigated in reports with a clear description.
thresholds for security alerts
Three thresholds are available: * **EPSS%:** When an EPSS score is available for a vulnerability (you can learn more about the Exploit Prediction Scoring System [here](https://www.first.org/epss/)) this threshold can be used to automatically mitigate vulnerabilities below the selected value. Please note that if a vulnerability does not include an EPSS evaluation this threshold is ignored * **CVSS**: When a CVSS score is available for a vulnerability (you can learn more about the Common Vulnerability Scoring System [here](https://www.first.org/cvss/)) this threshold can be used to automatically mitigate vulnerabilities below the selected value. * **SEVERITY:** A vulnerability will always have a Severity level associated to it among the values CRITICAL (highest), HIGH, MEDIUM, LOW, SUGGESTION, and INFORMATIONAL: this threshold can be used to automatically mitigate vulnerabilities below the selected value. #### **Analysis scopes**
the three analysis scopes
When Meterian analyzes your code, it detects which components are part of your shipped product (the "production" dependencies) from the rest of the dependencies. You can then here decide which ones are taken into account when computing each score. **Notification configuration (Sentinel)** ![](/files/hVcyVjxTdixZztMvoqnk) If in your account [Sentinel notifications](/notifications/sentinel) are enabled, you can configure the minimum threshold to receive a notification when a new vulnerability is affecting your product, and also if you want to be notified about libraries that appear to be unmaintained. **Manipulating advisories severity levels** ![](/files/3ZFrCQITpN6CwKNTLq5i) You can enforce an arbitrary level of Severity when an advisory does not have a CVE associated. If an advisory is related to an unmaintained library, you can also enforce an arbitrary security level. If select NONE, such advisories won't influence the score. **Excluding from license analysis group of components** ![](/files/D6M5CdcEXibqBA8e9q3g) **Miscellaneous** You can select the default time filter for the projects view. ![](/files/gBagrPwGl7CgUTYHhVBY) # Automatic Temporary Branches Clean-up
Using the dashboard it is possible to configure your account to automatically delete all reports which come from a particular branch after it has not been scanned for a given period of time. You can enable/ disable this feature using the "Automatic temporary branches cleanup" toggle button. You can adjust the behaviour of the cleanup procedure using the following variables. ## Protected Branches Regex If a project branch is being considered for deletion and the branch name matches this regex \ it will not be deleted. ## Temporary Branches Regex If a project branch is being considered for deletion and the branch name matches this regex it will be deleted if the branch name does not also match the protected branch regex. ## Temporary Branches Lifetime In Days If the last report of a project branch was made N or more days ago it will be considered for deletion, where N is the temporary branches lifetime in days. # Advanced functionalities In this section you will find a brief description of some advanced functionalities: * [how to configure multi-factor authentication (MFA)](/the-meterian-webapp/advanced-functionalities/multi-factor-authentication) * [how to generate Software Bill Of Materials](/the-meterian-webapp/advanced-functionalities/software-bill-of-materials-sbom) * [how the suggested safe versions mechanism work](/the-meterian-webapp/advanced-functionalities/safe-versions) * [how to use auto-grouping](/the-meterian-webapp/advanced-functionalities/auto-grouping) * [how to setup a vulnerability exclusion](/the-meterian-webapp/advanced-functionalities/set-exclusion) # Multi-factor Authentication The Multi-factor authentication enhances the security of your Meterian account. This is an optional feature that has to be specifically requested. Once the multi-factor authentication (MFA) feature is enabled, on login, users are required to verify their identity via a time-based one-time password (TOTP) sent by email.
Once authenticated the users can set a variety of factors: * Authenticator app * SMS * Backup codes * Email Such factors can be configured from the section **Details > User**.
After the user’s identity has been verified, it will remain valid for for the same device 14 days # Safe versions How the suggested safe versions mechanism work When one or more vulnerabilities are identified in a certain version of a component, Meterian will automatically suggest you a list of "safe versions" to use. These appears in the project report, in a box positioned on the right of the component card, like in this example.

A vulnerable component and its safe versions

Here we can see that this component, "image", is affected by one vulnerability in its current version, "0.23.11". The "Safe versions" box indicates which versions are considered "safe" for Meterian, and in this specific case those are 0.23.14 (a patch update) and 0.24.6 (a minor update). Meterian infact "knows" about all versions of the component, and the vulnerabilities associated to each of them, as can be seen opening the correspondiing [link to Componentpedia](https://www.meterian.io/components/rust/image/), Meterian's libraries of components:

List of versions and vulnerabilities from a Componentpedia page

If we go back to the report, however, we notice that that particular vulnerability is declared to be fixed in version 0.23.12: why Meterian is suggesting version 0.23.14? This happens because, if there's a later patch which is safe and possibly fixes bugs, that will be the one suggested. This will improve the stability of your project. Given a semantic portion of the version (patch, minor, major) Meterian will always suggest the latest possible safe option. For this same reason, when multiple vulnerabilities are affecting a component, Meterian will compute the safest version possible, like in this example;

Multiple vulnerabilities affecting a component

Sometimes it's impossible to automatically find a safe version. For example, in this case, a vulnerability declares that a certain version of a component fixes it: however such version is actually not present in any public repository! Version 4.3.1 of System.IO.Compression.ZipFile was unfortunately never published on the .NET repository [Nuget.org](https://www.nuget.org/packages/System.IO.Compression.ZipFile#versions-body-tab).

The vulnerability says there's a fix, but no such component version exists in the package repository

Sometimes a safe, not vulnerable version is simple not available: in that situation you will want to consider alternative actions to resolve the issue, for example looking at mitigation factors or replacing the component altogether. # Software Bill Of Materials (SBOM) Generating various Software Bill Of Materials (SBOM) and bibles Meterian is able to generate different SBOMs in various formats. The available formats are: * **License Bible,** available in JSON or PDF formats, contains: * the full list of components with their licenses and copyrights statements * the complete text of all licenses used in the codebase * **Classic SBOM**, available in CSV format, contains: * the full list of components, with their licenses, copyrights statements and registry URL * **CycloneDX SBOM**, available in JSON and XML format (see the [CycloneDX specification](https://cyclonedx.org/specification)) From the web UI of a project report, click the drop down button next to the "Download Report PDF" button
Alternatively, generate the SBOM of your liking from the command line via one of the various clients/scanners. Read up the "[Producing reports](/the-client/command-line-parameters/producing-reports)" page for more information on how that is done. # Auto-grouping When a user registers on the platform it is uniquely identified by his email. New users usually get a fresh new opensource account, but if their email domain is recognized to be of a company that has a paid account in Meterian, then the new user is added to that account. # Domain auto-grouping When a user registers on the platform it is uniquely identified by his email. New users usually get a fresh new opensource account, but if their email domain is recognized to be of a company that has a paid account in Meterian, then the new user is added to that account. Note that there are obvious exclusions such as the usage of a "free" email is used, like "gmail.com" or "hotmail.com", So, if the company "acme.com" starts a paid subscription to Meterian, then all the users with an email in the same domain will be added automatically to such account. It is also possible to group user into an account based on the Github organisation they belong to. This is available for organisations on GitHub, and [it can be set up](/the-meterian-webapp/advanced-functionalities/auto-grouping/how-to-set-an-organization) using the Meterian dashboard. # Github auto-grouping In accounts where the "auto-grouping" feature is enabled, admin can select an organization from the ones they own on Github. From that point on, when a user logs in with GitHub, it will be checked if it belongs to such an organisation and, in that case, it will be automatically added to the account. Please note that you will need to have the feature enabled in your account to use this mechanism so get in touch with support if the need arises. ### How to activate it Navigate to the Details tab in the Meterian dashboard and click "Change..." on the Github organization section. \ The organization displayed in the "Github Organization" field shows the Github organization currently linked to the Meterian account. \ If the field is empty, that means that no organization is currently linked. ![](/files/-MJlwQufdbWEzTMGxFSS) And now it will be possible to select the organization from the menu. ![](/files/-MJlwrEOF9khQ3jCeo1F) * Users need to login using the Github option * Users won't see the "Github organization" field if they are not an admin of any Github organization or if the access permission to their organization has not been granted ### For new accounts One important thing to keep in mind is that on the very first login with Github, users are asked for permissions in order to interact with their Github account and Organizations (based on ownership status or GitHub-specific permission you may be prompted to request permission on certain organisations). Organization access permissions should be granted to enure this functionality works as expected ![](/files/-MJlvHW6I6465KqBZnh6) ### For existing accounts If you already created an account on Meterian, it's possible to grant permission to access a Github organization directly from the Github web application. From select "Meterian login" and grant access to the organization which should be linked to the Meterian account. {% hint style="info" %} The user must be both the administration of the Meterian account and of the Github organization in order to link the organization to the Meterian account. {% endhint %} When the access to the organization has been granted by the organization admin, the user must perform a new login into the Meterian dashboard {% hint style="info" %} Meterian will start grouping user of the same Github organization once the permission are granted and the Github organization is set in the "Details" view. {% endhint %} # How to set a vulnerability exclusion Exclusions are a way to ignore vulnerabilities so they would not affect the scores. Although this is a very useful feature it is highly recommended to handle it with extra care. Users can set a vulnerability exclusion from the [Report page](/the-meterian-webapp/advanced-functionalities/set-exclusion/set-exclusions-report-page), the [Meterian Dashboard](/the-meterian-webapp/advanced-functionalities/set-exclusion/from-the-dashboard) or from the codebase using the [.meterian](/the-meterian-webapp/advanced-functionalities/set-exclusion/dotmeterian) file. # From the report page **Set an exclusion from the report page** In the **Security** section, find the desired vulnerability, open the Actions tab and click on one of the options: ![](/files/-MLh_ksXc37GlcILtKSR) In the **Stability** section, click on the Ignore button related to the library you want to ignore: ![](/files/-MHM94DvXbYeq4bm7tlh) In the **Licensing** section, click on the Exclude button related to the library you want to exclude: ![](/files/-MHM9S4Kn6Vlm2D8za8c) When required, remember to type a meaningful description before confirming the exclusion: ![](/files/-MHMGZOgUGO5KFl1gsMk) **Trust a component** In the security assessment, it is also possible to mark a specific component as **Trusted** so that all the transitive vulnerabilities, the ones carried by its dependencies, dot not affect the security score of the project. {% hint style="info" %} The vulnerabilities related to the component itself will be included in the security assessment. {% endhint %} To mark a component as **Trusted** simply open the Hierarchy tab (if present), hover on the component to mark as Trusted and a "Trust component" button will appear. ![](/files/AXnBuyqF1h1QdLCPFguf) When required, remember to type a meaningful description before confirming the exclusion: ![](/files/hL2nZZOZ9sfw5ebKV6rq) This type exclusion will, in every case, trigger a recompute of the security section of the report. # From the dashboard **Set exclusions for the whole account** Exclusion can also be set for the whole Meterian account with an active 'insights' feature. \ Account admins can use the account wide exclusion switch within the Insights panel for any library. ![](/files/-MHMCi27p1TQiDbtD9ds) Navigate to the Insights tab ![](/files/-MHMCyte07GLoMpSJ8QT) Click on any library and use the Exclusion switch to exclude the vulnerability for the whole account # The .meterian file To set an exclusion from within the codebase create a file named '.meterian'. The .meterian file is bound to have the structure specified below: ``` { "exclusions": { "licensing": { "libraries": [{ "library": { "language": "ruby", "name": "rspec" }, "version": "*", "description": "Internal library by Acme inc. so a license is implied" }] }, "security": { "advices": [{ "uuid": "ffb4763c-7af7-4499-804e-11165888e1f3", "reason": "mitigated", "description": "We are not using this" }], "cves": [{ "cve": "CVE-2018-1783", "reason": "mitigated", "description": "We are not using this" }], "libraries": [{ "library": { "language": "ruby", "name": "rack" }, "version": "*", "description": "Check if exclusion on library works!" }] }, "stability": { "libraries": [{ "library": { "language": "java", "name": "acme*" }, "version": "*", "description": "Acme on java is notorioiusly stable" }] } } } ``` ### **Security exclusions** There are three different type of security exclusions: * **Advices**: This exclusion is very similar to the one users can set from the report page as it only affects the single vulnerability. This type of exclusion can be set only if the vulnerability UUID is known to the user. * **CVE**: This exclusion affects all the vulnerabilities with the specified CVE ID * **Libraries**: This exclusion affects all the vulnerabilities related to a specific version of a library ### **Accepted Values** **Security** ``` { "exclusions":{ "security": { "advices": [{ "uuid": "ffb4763c-7af7-4499-804e-11165888e1f3", "reason": "mitigated", "description": "We are not using this" }], "cves": [], "libraries": [] } } } ``` * **uuid**: "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" - *(it has to have this format and it must be known by the user - unique vulnerability identificator provided by Meterian)*. ``` { "exclusions":{ "security": { "advices": [], "cves": [{ "cve": "CVE-2018-1783", "reason": "mitigated", "description": "We are not using this" }], "libraries": [] } } } ``` * **cve**: "CVE-XXXX-XXXXX" - *(it has to have this format and it must be a valid CVE id - unique vulnerability identificator and it is provided by Mitre and NVD)*. ``` { "exclusions":{ "security": { "advices": [], "cves": [], "libraries": [{ "library": { "language": "ruby", "name": "rack" }, "version": "*", "description": "Check if exclusion on library works!" }] } } } ``` * **library - language**: java | dotnet | python | nodejs | ruby | javascript | php | swift | golang - *(name of the language the library code is written in).* * **library - name:** the exact name of the library to exclude. * **version**: the exact version of the library to exclude | \* will exclude all the versions. **Common fields** * **description**: It has to be a text, we suggest a meaningful description of the reason why the vulnerability is being excluded. * **reason**: report | unapplicable | mitigated - *(a different value or the omission of this field will replaced by the default value 'unapplicable')*. **Stability** ``` { "exclusions":{ "stability": { "libraries": [{ "library": { "language": "java", "name": "acme*" }, "version": "*", "description": "Acme on java is notorioiusly stable" }] } } } ``` * **library - language**: java | dotnet | python | nodejs | ruby | javascript | php | swift | golang - *(name of the language the library code is written in).* * **library - name**: name of the library - *(a glob pattern can also be used in field to exclude more than one library).* * **version**: version of the library to exclude | \* will exclude all the versions - *(a glob pattern can also be used in field to exclude more than one version).* * **description**: It has to be a text, we suggest a meaningful description of the reason why the vulnerability is being excluded **Licensing** ``` { "exclusions":{ "licensing": { "libraries": [{ "library": { "language": "ruby", "name": "rspec" }, "version": "*", "description": "Internal library by Acme inc. so a license is implied" }] } } } ``` * **library - language**: java | dotnet | python | nodejs | ruby | javascript | php | swift | golang - *(name of the language the library code is written in).* * **library - name**: name of the library - *(a glob pattern can also be used in field to exclude more than one library).* * **version**: version of the library to exclude | \* will exclude all the versions - *(a glob pattern can also be used in field to exclude more than one version).* * **description**: It has to be a text, we suggest a meaningful description of the reason why the vulnerability is being excluded For every single type of exclusion some of the fields are mandatory, and the wrong usage could lead to an invalidation of the exclusion. # Generate the .meterian file For ease of use, the [.meterian](/the-meterian-webapp/advanced-functionalities/set-exclusion/dotmeterian) file can also simply be download from the [Report page](/the-meterian-webapp/advanced-functionalities/set-exclusion/set-exclusions-report-page), after exclusion has been set up there. Just click on the "Download Exclusions" button available on the first row: ![](/files/-MLhYlAN9KbRGrH8hM6Q) Then place the downloaded file as ".meterian" in the root project of your folder. It's a simple mechanism that can also be used to replicate your exclusions across several branches of the same codebase. # SSO Configuration In this page you can configure single sign-on (SSO) for your account. Each supported SSO type has its own tab inside the configuration page, and **only account administrators** can see and edit these tabs. {% hint style="warning" %} **Note:** Each SSO type is bound to its own feature flag, which must be enabled on your account before its tab becomes available. To have SSO enabled, contact Meterian sales and request the feature flag for the SSO type you want to use. {% endhint %} Each tab contains the form for that SSO type, a "Save" button, and — once a configuration exists — a "Delete" button, the login URL to share with your users, and any extra section required by that SSO type (such as the attribute mapping for SAML 2.0). You can have at most one active configuration per SSO type. The fields you have to fill in depend on the SSO type. See the page for the type you want to set up: * [Azure AD](/the-meterian-webapp/advanced-functionalities/sso-configuration/azure-ad) * [SAML 2.0](/the-meterian-webapp/advanced-functionalities/sso-configuration/generic-saml-2.0) To provision and de-provision users and teams automatically from your identity provider, see the [SCIM API](/the-meterian-webapp/advanced-functionalities/sso-configuration/scim-2.0), the companion to SSO. ### Create or update a configuration Open the tab for the SSO type you want to configure and fill in the form. Required fields are marked with an asterisk. Some fields accept multiple values: type a value and press Space, Enter or comma to add it as a tag, and click the × on a tag to remove it. Click "Save" to apply your changes. The "Name" field identifies the configuration and becomes read-only once saved — pick it carefully, as it cannot be changed later without removing and recreating the configuration. If the server rejects the values, the error is shown above the form and the configuration is left untouched. ### Share the login URL Once the configuration is saved, a "Login URL" section appears at the bottom of the tab with a read-only URL and a "Copy" button. Share this URL with the users who should log in via SSO. They will be taken straight to your identity provider instead of the standard login page. ### Remove a configuration To remove a configuration simply click the "Delete" button and confirm in the dialog that follows. The configuration is deleted from the server and the form is cleared, so the "Name" field becomes editable again and the SSO type can be configured from scratch. It's a good policy to remove configurations that are no longer in use, and to keep the "Name" descriptive enough to recognise which identity provider it refers to. # Azure AD In this page you can find guidance on how to set up the Azure AD tab in the [SSO configuration](/the-meterian-webapp/advanced-functionalities/sso-configuration). Before you start, you need to have registered an application in your Azure AD tenant so that the dashboard can authenticate users against it. The values to enter in the form come from that application's settings. ### Fields **Name** — a label that identifies this configuration inside Meterian. Only letters, numbers, hyphens and underscores are allowed, and it cannot be changed once saved. **Tenant ID** — the identifier of the Azure AD tenant that owns the application. You can find it in the Azure portal under "Microsoft Entra ID" → "Overview" as "Tenant ID". **Client ID** — the application (client) ID of the registered app. In the Azure portal, open the app registration and copy the value listed as "Application (client) ID". **Client Secret** — a secret created for the same app registration, under "Certificates & secrets". Make sure to copy the secret value at creation time, as Azure will not show it again. **Scopes** — the OAuth scopes to request when authenticating users. Type each scope and press Space, Enter or comma to add it as a tag. Meterian requires `openid`, `name`, `email` in order to work. The recommendation is to use the `User.Read` claim which provides all the three fields.
### After saving Once the configuration is saved, the "Login URL" section becomes available. Share that URL with the users who should log in via Azure AD — they will be redirected to Microsoft to sign in, and then back into Meterian. Azure AD does not require any extra attribute mapping: user identity is taken from the standard claims returned by Microsoft. ### Azure AD Teams {% hint style="warning" %} **Note:** Azure AD Teams is bound to its own feature flag, separate from the Azure AD SSO flag. It must be enabled on your account before the section appears — contact Meterian support to request it. {% endhint %} Once Azure AD SSO is saved, an “Azure AD Teams” section appears below it. This is where you tell Meterian which Azure AD groups grant access to the account and which ones map to your Meterian teams. The table has two predefined rows that you cannot remove: * **Everyone** — paste the Azure AD group ID whose members should have access to the Meterian account. Any user authenticated via Azure AD who is not in this group is denied access. * **Admins** — paste the Azure AD group ID whose members should be Administrators of the Meterian account. Membership of this group is the only way to grant the Administrator role when Azure AD Teams is in use. Below the predefined rows you can add additional associations: pick a Meterian team from the dropdown, paste the corresponding Azure AD group ID, and click “Add”. Users in that Azure group will be automatically added to the chosen Meterian team when they log in. You can edit or remove these custom associations at any time using the icons in the “Actions” column. While Azure AD Teams is active, the Teams page displays a notice — “Teams are managed by Azure Active Directory” — and the Administrator role can no longer be assigned manually from the Meterian UI: it is driven entirely by membership of the “Admins” Azure group.
# Generic SAML 2.0 In this page you can find guidance on how to set up the SAML 2.0 tab in the [SSO configuration](/the-meterian-webapp/advanced-functionalities/sso-configuration). Before you start, you need to have a SAML 2.0 identity provider (IdP) configured to issue assertions to Meterian. The values to enter in the form come from that identity provider. ### Fields **Name** — a label that identifies this configuration inside Meterian. Only letters, numbers, hyphens and underscores are allowed, and it cannot be changed once saved. **Metadata URL** — the URL where your identity provider publishes its SAML metadata document. Meterian uses it to discover the IdP's SSO endpoint and signing certificate. Most identity providers expose this URL from the application or connection you created for Meterian.
### Attribute mapping After saving, an "Attribute Mapping" section appears below the login URL. **Attribute mapping is required for this SSO configuration to work** — until it is set, users authenticated through your identity provider cannot be matched to a Meterian account. For each field, enter the name of the SAML attribute (or claim) your identity provider sends in the assertion. **Email** — the attribute that carries the user's email address. This is the value Meterian uses to identify the user. **Name** — the attribute that carries the user's display name. **User ID** — the attribute used as the stable unique identifier for the user. If left blank, the email address is used as the user ID. Click "Save mapping" to apply. If you change the mapping later, simply update the values and click "Save mapping" again.
### After saving Once both the configuration and the attribute mapping have been saved, the "Login URL" section can be shared with the users who should log in via SAML. They will be redirected to your identity provider to sign in, and then back into Meterian. # SCIM 2.0 Meterian exposes a [SCIM 2.0](https://datatracker.ietf.org/doc/html/rfc7644) REST API so that your identity provider (IdP) can provision and de-provision users and teams in your Meterian account automatically. It is the companion to [SSO configuration](/the-meterian-webapp/advanced-functionalities/sso-configuration): SSO controls *how* users log in, while SCIM keeps the list of users and their team membership in sync. {% hint style="warning" %} **Note:** The SCIM API is bound to its own feature flag, which must be enabled on your account before it can be used. Contact Meterian sales to request it. {% endhint %} ## Base URL All endpoints are served under: ``` https://www.meterian.io/api/v1/scim ``` Requests and responses use the `application/scim+json` content type. ## API explorer An interactive UI is available so you can browse the endpoints and try requests from the browser: The raw OpenAPI specification is served at ## Authentication The API uses **HTTP Basic** authentication. The credentials are your **account UUID** as the username and a **Meterian API token** as the password, joined with a colon and Base64-encoded: ``` Authorization: Basic base64(accountUUID:meterianApiToken) ``` You can find your **account UUID** in the dashboard under the **Details** tab, in the **Account** section: it is shown in the read-only "UUID" field, with a copy-to-clipboard button next to it.
Every request must carry this header, except for the unauthenticated discovery endpoints (`/ServiceProviderConfig`, `/ResourceTypes`, `/Schemas`). If the header is missing or invalid the API responds with `401 Unauthorized`. ## Endpoints ### Users | Method | Path | Purpose | | -------- | ------------- | ------------------------------------------------------------- | | `GET` | `/Users` | List users (supports `startIndex` and `count` for pagination) | | `POST` | `/Users` | Create a user | | `GET` | `/Users/{id}` | Fetch a single user by UUID | | `PUT` | `/Users/{id}` | Replace a user | | `PATCH` | `/Users/{id}` | Partially update a user | | `DELETE` | `/Users/{id}` | Remove a user | ### Groups (teams) Meterian **teams** are exposed as SCIM **Groups**. | Method | Path | Purpose | | -------- | -------------- | ---------------------------------------------- | | `GET` | `/Groups` | List teams (supports `startIndex` and `count`) | | `POST` | `/Groups` | Create a team | | `GET` | `/Groups/{id}` | Fetch a single team by UUID or name | | `PUT` | `/Groups/{id}` | Replace a team | | `PATCH` | `/Groups/{id}` | Add, update or remove members | | `DELETE` | `/Groups/{id}` | Delete a team | ### Discovery (no authentication) | Method | Path | Purpose | | ------ | ------------------------ | -------------------------------------------------------- | | `GET` | `/ServiceProviderConfig` | Capabilities advertised by the server | | `GET` | `/ResourceTypes` | Supported resource types | | `GET` | `/Schemas` | Schema definitions (`/Schemas/Users`, `/Schemas/Groups`) | {% hint style="info" %} Pagination only. The server advertises `patch: true` but `filter: false`, `sort: false` and `bulk: false` — listing endpoints support `startIndex`/`count` paging but not filtering or sorting. {% endhint %} ## Schemas The API uses the standard SCIM 2.0 schemas plus a Meterian extension that adds a **role** to group members: * User — `urn:ietf:params:scim:schemas:core:2.0:User` * Group — `urn:ietf:params:scim:schemas:core:2.0:Group` * Group member role (Meterian extension) — adds a `role` attribute to each entry in a group's `members` array. Valid role values are **Administrator**, **Collaborator** and **Viewer**. When a role is not supplied, the user defaults to **Viewer**. A user's `userName` must be a valid **email address**, and the email cannot be changed once the user has been created. ## Examples **List users** ```bash curl -s "https://www.meterian.io/api/v1/scim/Users?startIndex=1&count=100" \ -H "Authorization: Basic $(printf '%s' "$ACCOUNT_UUID:$METERIAN_API_TOKEN" | base64)" ``` **Create a user** ```bash curl -s -X POST "https://www.meterian.io/api/v1/scim/Users" \ -H "Authorization: Basic $(printf '%s' "$ACCOUNT_UUID:$METERIAN_API_TOKEN" | base64)" \ -H "Content-Type: application/scim+json" \ -d '{ "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "userName": "example@acme.com", "name": { "givenName": "Example", "familyName": "User" }, "roles": [{ "value": "Collaborator" }] }' ``` **Add a member to a team** ```bash curl -s -X PATCH "https://www.meterian.io/api/v1/scim/Groups/{teamId}" \ -H "Authorization: Basic $(printf '%s' "$ACCOUNT_UUID:$METERIAN_API_TOKEN" | base64)" \ -H "Content-Type: application/scim+json" \ -d '{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [{ "op": "add", "path": "members", "value": { "display": "Example User", "value": "example@acme.com", "type": "User", "role": "Collaborator" } }] }' ``` The `Operations` array also accepts `replace` (to change a member's role) and `remove` (to take a member out of the team). ## Errors Errors are returned as SCIM error messages with the matching HTTP status code: ```json { "status": 400, "message": "The userName field is required to be an email address.", "scimType": "invalidValue" } ``` Common cases: | Status | Meaning | | ------ | ------------------------------------------------------------------------------------------------------ | | `400` | Invalid or missing field (e.g. `userName` is not an email, or an attempt to change an immutable email) | | `401` | Missing or invalid `Authorization` header | | `500` | Unexpected server error | # Troubleshooting We track here solutions to common issues we troubleshoot. # Login with credentials **My Login with credential keeps failing but I know my details are correct. What should I do? \***‌ Third-party cookie blocks could prevent the Meterian Dashboard from successfully completing the login flow. Try disabling the third-party cookie block from the Privacy Setting of your browser.‌ * **Chrome** * Go to Settings > Privacy and Security * Under Cookies and other site data Select “Allow all cookies” * Please note that in Chrome you can also select to "Block all cookies" and then whitelist the specific Meterian site you are using * **Firefox** * Go to Preferences > Privacy and Security * Select “Standard” * **Edge** * Go to Settings > Advanced Settings * Click on Site Settings and then open Cookies section under Permissions * Turn ‘Allow sites to save and read cookie data’ ON * Turn ‘Block third-party cookies’ OFF * **Safari** * From the Safari menu go to Preferences > Privacy * Disable ‘Block all cookies’ * Disable ‘Prevent cross-site tracking’ # Sentinel Be alerted of new vulnerabilities after your application went live. Sentinel is a new service which makes it possible for Meterian users to receive notifications about newly found vulnerabilities which are affecting libraries used on the projects in their Meterian account. If an application was scanned by Meterian and then went live, with no subsequent scans, Meterian still retains the structure of such application in terms of opensource components: if Sentinel is enabled, following daily checks run on the system, it can raise an alert when any new vulnerability is discovered, so that the appropriate remediation can be put in place. For more information about activation and prices please contact . **The Notification** The notification is related to the offending opensource component. The receiver will find detailed information about all the new vulnerabilities found since the last Meterian scan, and a list of all the projects related to the team of which the receiver is an admin. [Notification for Slack](/notifications/sentinel/slack) Notifications for Slack are either active or inactive for the whole team/account. When enabled, they will be directed to the Slack channel configured by the administrator. [Notification for Email](/notifications/sentinel/email-notification) Notifications for Email can be received by account admins or team admins. When enabled, they will be directed to the email account of the selected administrator. Your privacy is important to us. By activating Meterian notifications, you agree to our [Privacy Policy](https://www.meterian.io/gdpr.html). We are committed to protecting your data and ensuring that it is used only for the purpose of delivering these security notifications. # Notifications for Slack Meterian notifications for Slack ensures you're always informed and empowered to take immediate action against potential security risks in your open-source components.\ [Learn more about the Meterian's Sentinel notification service](/notifications/sentinel).\ \ **How it works in Slack**\ Meterian Sentinel continuously checks the security of your projects, sending a notification to the configured Slack channel every time a new vulnerability is discovered and it affects your projects. The notification contains an overview of the vulnerable component, including the latest discovered vulnerabilities, and all the list of the projects affected by it, giving the user relevant informations to take actions to secure their software as fast as possible.

Example of Meterian Sentinel notification in Slack

*** **Get started**\ Notifications for Slack can be enabled from the Meterian Dashboard. An admin will choose the Corporate Slack channel in which notifications are sent by Sentinel. Login using your credentials or social account from the [Meterian Dashboard](https://www.meterian.io/dashboard)\ Then activate the notification following the steps below {% tabs %} {% tab title="For account with Teams management" %} If the Teams management feature is active on your account, notifications can be activated by selecting the option from the team actions panel

Open the Teams tab on the Meterian dashboard

Click on the action button, then click on "Activate Slack Notifications"

{% endtab %} {% tab title="For account without Teams management" %} If the Teams management feature is not active in your account, navigate to the "Details" tab, then activate the notifications for Slack from the "Notifications" section

Open the Details tab on the Meterian dashboard

Click on "Activate Slack Notifications"

{% endtab %} {% endtabs %} To finalize the activation select the Slack channel where to receive the Meterian Sentinel notifications ![A permission request form, handled by Slack, will be opened in a new page. Select here the channel where the notifications are to be sent.](/files/487UawggBTe9EGA7MPil) Your privacy is important to us. By activating Meterian notifications for Slack , you agree to our [Privacy Policy](https://www.meterian.io/gdpr.html). We are committed to protecting your data and ensuring that it is used only for the purpose of delivering these security notifications. # Notifications for Email A team admin can activate the email notifications for their email address related to that Meterian account. They can choose to disable the notifications service for their email address at any time. An account admin can enable or disable the notifications service for any account/team admin in their Meterian account. The notifications can only be received by account admins or team admins. * For accounts with Teams management feature. ![Open the Teams tab on the Meterian dashboard](/files/-M9YQ7OvgX6Aj1UvFwYP) ![Click on the action button, then click on "Activate Email Notifications"](/files/-M9YS__QZ6cXcjxccP1S) * For accounts without Teams management feature. ![Open the Details tab on the Meterian dashboard](/files/-M9YUwJ9GWNMKG9cgX9O) ![ Click on "Activate Slack Notifications"](/files/-M9YVqIpiQbxJ1X-PoQk) # Allerta Receive emails about new vulnerabilities based on your interests Allerta is a notification system that gives timely alerts to any member of the account for any new vulnerability discovered based on the interests of the user. Each user can register his preferences in terms of ecosystems, scoring thresholds (based for example on the exploitability of a vulnerability) and receive notifications daily each time Meterian detects a new vulnerability that matches such specifications. Developers can receive alerts focused on their specifc language of interest, while security personnel can get a broader view, while receiving precise information as all notifications include the specific component and version affected.
The Allerta feature has to be enabled in the configuration of the account. Allerta sends notifications exclusively via email.
# Introduction Research is, by all means, one of the most crucial steps of the consumer decision-making process, and because of this giving a clear, direct and strong signal of the top-notch quality of your product might be a key selling point.\ \ Github Badges are a simple and straightforward way to present products in the best possible way and to save developers precious time by keeping track of the product security score automatically. In this section you will learn how to create Meterian security, stability and licensing badges for [public repository](/badges/github) and [private repository](/badges/private-repository). # Public repository Generating a badge for your repository is very simple and will create and refresh a report of your project' vulnerabilities so you do not have to worry about outdated reports. The first thing you have to do is [login](https://www.meterian.com/account) into your Meterian account and, once logged in, navigate to the 'Badges' tab.\ Here you will find a text field where to type or paste your github project url, for example `https://github.com/spring-projects/spring-boot` A project branch can also be specified, although it is not mandatory. Clicking on Generate some snippets will be created in the area below. `[![security status](https://www.meterian.com/badge/gh/spring-projects/spring-boot/security)](https://www.meterian.com/report/gh/spring-projects/spring-boot)` Copy and paste the snippets on your projects README.md file and the badges looking like this![security status](https://www.meterian.com/badge/gh/spring-projects/spring-boot/security) will appear on your github project README. This badge is also a direct link to the Meterian project report page. The report for your project will be automatically created (if not existing) and automatically refreshed daily. # Private repository It is quite common for organizations to hide their source code using private repositories but sometimes you or your organization might want to publicly show the vulnerabilities report for your project. You can do that by [logging in](https://www.meterian.com/account) with your Meterian account, then navigate to the tab "Projects" and you will be able to mark a project as Public. Once you do that you will enable the private badge feature on the "Badges" tab. Simply select the project, the branch (optional) and click on 'Generate'. Some snippets will be created in the area below. `[![security status](https://www.meterian.com/badge/pb/e315f215-3d85-4b63-8618-a69f2175d0a7/security)]()` Copy and paste the snippets on your projects README.md file and the badges looking like this![security status](https://www.meterian.com/badge/pb/e315f215-3d85-4b63-8618-a69f2175d0a7/security) will appear on your github project README. This badge is also a direct link to the Meterian project report page. The report for your project will be automatically created (if not existing) and automatically refreshed daily.
# Introduction How to integrate with cloud code repositories like GitHub or Azure Using Meterian with a cloud code repository is very simple, especially when a native integration is available from the local marketplace. At this time we have native integrations with these cloud platforms: * [GitHub](/online-integrations/meterian-scanner-github-action) via GitHub actions * [Bitbucket](/online-integrations/meterian-scanner-bitbucket-pipelines) via Pipes * [Azure Devops](/online-integrations/azure-devops-pipelines) via Extensions We of course offer non-native integrations for all other major platforms, and you can find all of them in [this section](/ci-server-integrations/introduction). # GitHub Action The [Meterian Scanner GitHub Action](https://github.com/marketplace/actions/meterian-scanner) enables you to automate a vulnerability scan of your codebase right from the GitHub repository. Our action can be triggered by any GitHub workflow event, and combined with countless existing actions giving you the freedom to customise your software development workflow around it however you please. Follow the [first scan guide](/the-client/guide-your-first-scan/your-first-scan-github-action) to set our action up in your repository, or find out more about it on the [documentation on GitHub](https://github.com/marketplace/actions/meterian-scanner) to learn about its configuration and how to integrate it into your existing workflow. Please note that in order to use this integration for private codebases you will need to be on any of our paid plans. A list of working examples for all the supported languages can be found [here](https://github.com/marketplace/actions/meterian-scanner#examples). --- [Next Page](/llms-full.txt/1)