Creating an Integration with your SCM

First, go to Home >> Managed Scans

Click on Add Repository button to create an integration with your SCM. A dialog will open to select your SCM:

For this example, we will use GitHub. So clicking on GitHub will install Xygeni GitHub Application.

As you can see below, the installation procedure will let you specify the scope of the installation (user- or organization-level)

The installation will ask you to grant permission to Xygeni GitHub Application to all or only selected repositories.

After clicking on Install & Authorize button, the Managed Scans page will display the new integration.

It also display a table listing the granted repositories (this list depends on previous step).

Clicking on the Scan Now button of any repo will execute a scan on that repo.

If you go now to GitHub, you will see a workflow running the scan:

That's all!!

If you are a new Xygeni user and you want to see its capabilities in the easiest way, please follow these steps.

Execute a scan from the Xygeni Web UI (easiest method)

To scan a repository located in your preferred SCM, the easiest method is to do it directly from the Xygeni Web UI.

Execute a scan using Xygeni CLI

You can also follow an alternative approach by using the Xygeni CLI, although it is not as direct as using the Web UI. The Scanner CLI allows you to scan a local directory or a remote repo directly from a command shell or a shell script.

I don't want to scan, I just want to see a demo project

If you only want to see preloaded results, you can load into your account pre-built results of a demo project that will show you representative examples of issues (this option will not scan any source code).

A Scan is the action performed by the Xygeni Scanner to find security issues in your project.

You can follow the steps below for a quick start guide to using the Xygeni CLI

1. Install the Scanner CLI

An installation script is provided for automated installation.

The recommended, automated way to install the scanner is to use the installation script.

The Xygeni installation scripts provided by Xygeni as a way to speed up your xygeni experience by setting your scanning environment as fast as possible.

Download the script

Run one of the following commands depending on your preferences:

  curl -sLO https://get.xygeni.io/latest/scanner/install.sh

 iwr https://get.xygeni.io/latest/scanner/install.ps1 -useb -OutFile install.ps1

2. Fetch your Xygeni account credentials or API token

An Access Token, also referred to as an API token or API key, is used by applications such as the Xygeni Scanner or other integrations to access the Xygeni platform's API.

Describe what the token will be used for, choose the validity period, and select the permissions granted to the token. Click on the Generate button:

Finally, the token is generated:

3. Run the installation script

The variable XYGENI_TOKEN refers to an environment variable that stores the Xygeni API token. This token will be used to authenticate with the service.

./install.sh -o -v -t $XYGENI_TOKEN

PS .\install.ps1 -o -verbose -t $Env:XYGENI_TOKEN

For a list of available options, execute ./install.sh --help on Unix-based systems or PS .\install.ps1 --help on Windows.

4. Run your first scan

To begin, ensure that you have a file system folder containing your project content. This folder may be a clone of your repository or simply a directory housing the source code for your project.

Navigate to your project directory, with the command cd /my/project. Once there, initiate a scan by running xygeni scan. All vulnerabilities identified are listed, including their path and fix guidance.

$ cd /my/project
$ xygeni scan 

You can also use these commands below for other cases:

# Assuming that $XYGENI_HOME in path or xygeni shortcut set
# Scan a directory
$ xygeni scan -n <your_project_name> --dir <path_to_analyze>

# Scan a repository
$ xygeni scan --repository <repo_url>

# Scan a container image
$ xygeni scan --repository <image>

# You may add --no-upload to the scan command if you want to view
# the results before uploading to Xygeni platform. 

5. View scan results

After signing up, you will be presented with three options.

The "Try out a Demo Project" option lets you explore a demo project with preloaded data, eliminating the need to scan a real repository.

Select "Try out a Demo Project" to initiate the background process to load the demo project.

Click on the Close button and you will see that a new project has been created (named "DemoProject") with preloaded data. You can freely browse for any page to see funnel, dashboards, risks, etc.

Secure your Software Development and Delivery

Enhance your Application Security Posture Management (ASPM) through comprehensive risk assessment, strategic prioritization, and protection against attacks and malware infection throughout your Software Supply Chain

Start using Xygeni

Intro to Xygeni

Xygeni Configuration and Administration

Subscribe to Xygeni

After you finish your trial period you can upgrade your plan to continue monitoring and improving the security of your applications and organization.

To manage your plan and review scan utilization, please navigate to Settings >> Subscription

Access to Subscribe section

Open the Settings menu and select Subscription. The subsequent screen with appear:

Subscribe

Once you've chosen your subscription preferences, you'll be directed to a secure external payment platform. Xygeni does not store or handle any payment details or personal information related to your transactions.

Your license will be updated upon successful payment confirmation, allowing you to utilize the Xygeni platform.

Projects

A project is the target for the scans. It can be any unit of software that can be analyzed independently, with any granularity. It could correspond with an application, module, service, microservice, container image, library, component…​

A project typically is under version control, and it consists of a set of source files, often grouped as a repository in a Source Code Management (SCM) System.

You need a Xygeni Account to use Xygeni functionalities.

Create a Free Trial account

Xygeni offers a comprehensive set of features for evaluation over a 14-day trial. The registration process requires no payment details, and no automatic subscription is initiated post-trial. Should the user choose not to subscribe, the account will be deactivated.

2. Choose your preferred signup method.

First Login to Xygeni

• As the first user in your Xygeni organization, you are designated as the main administrator (owner), granting you full permissions to create new user accounts, edit projects, and set up policies. Upon creating the Xygeni account, you will receive a notification email to set up a new password.

• As a new user in an existing Xygeni Organization, you will receive an email notification to set your password

Clicking on Set a new password button will redirect you to Reset Password dialog.

Upon successful password creation, the application will launch, starting you off on the Home page.

Project's Baseline

Every project in Xygeni has a Baseline.

A Baseline is a definitive analysis of the project used as a reference point for comparison with subsequent analyses, primarily to track the progression of issues within the project.

By default, a project's baseline is established by the initial scan. However, you have the option to designate a specific scan as the new baseline.

Each standard is composed of a set of checkpoints that are evaluated against the project under analysis. A checkpoint is classified within a specific category and may be designated as mandatory or optional. The outcome indicates whether the project meets the standard, providing a compliance level assessment

Risk Level

The Risk Level (RL) is a quantitative metric that assesses the current exposure to software supply chain attacks. It evaluates the security posture of the DevOps system based on scans conducted by the Xygeni platform.

The Risk Level is quantified on a scale from 0 to 100, with 100 indicating the highest level of risk. This measure is determined by the issues identified within a project. If no issues are detected, the Risk Level is rated as 0.

The RL is qualified in three categories that make more evident how good or bad is the risk for the organization. Each category is encoded with a color following the "semaphore" scheme:

• Low: RL between 0 and 33, green color.

• Moderate: RL between 33 and 66, yellow color.

• High: RL between 66 and 100, blood-red color.

Modern software complexity demands an equally sophisticated build and deployment infrastructure.

Software is typically built and deployed in production environments using pipeline commands. A build/deploy pipeline is based on a set of automated processes and tools, involving source control, build tools, continuous integration, testing automation (unit, integration and regression testing), validation, reporting, and distribution.

The build/deploy pipeline assets, known as SDLC assets, are automatically discovered in the Xygeni platform. This creates an inventory of SDLC assets for the pipelines used within an organization.

An SDLC Asset may present misconfigurations, leaked secrets, and other security issues which could be abused in software supply chain attacks. Common assets are code repositories, dependency graphs, package managers, build files, security tools, CI/CD workflows or IaC templates and provisioning scripts, along with the infrastructure, tools and extensions (such as plugins) used in the build / deploy pipelines.

Security issues and unusual activity events are mapped to the target SDLC assets. The Inventory allows to reveal unknown, misconfigured and vulnerable SDLC systems and infrastructure, and perform impact analysis: dependencies between assets may be exploited by attackers to propagate the attack payloads.

The scan findings or security issues represent misconfigurations, flaws or anomalies that increase the risk of a successful software supply chain attack.

Each issue could be found by a detector, which can be thought of as the unit of analysis. Running a set of detectors over the target software project is a scan. Scans for each issue type can be analyzed separately or in a single run.

Below are the types of issues encountered in Xygeni:

Vulnerable Dependencies

A dependency is vulnerable when some programming defect or flaw can be exploited with malicious intent. Do you remember Log4J ? That dependency is not malicious, just vulnerable. Someone found a trick to exploit a flaw in the source code of the dependency that could be used to gain improper access to some resource.

Suspect Dependencies

A Suspect Dependency models a dependencies issue, a defect in project dependencies that may open the door to software supply-chain attacks.

A classic example is having an indirect dependency which was compromised by an actor to inject malware in the software that depends on that component. The actor may inject malicious code and indirectly attack the organizations that use the affected version(s) of the malware component.

CI/CD Misconfigurations

A CI/CD misconfiguration is any flaw in the configuration of a tool that could allow bad actors to perform unintended operations affecting the software pipeline.

There are many systems in the software pipeline that could have a misconfiguration: management systems, build tools, package managers, registries, compilers, testing frameworks, IDEs, CI/CD systems, provisioning tools, container frameworks and orchestration tools…​

Examples of misconfigurations are:

• Unprotected delivery code branches.

• Lack of code reviews.

• Poor access control practices like the lack of multi-factor authentication.

• Publicly accessible storage buckets in the cloud infrastructure.

• Flaws in CI pipelines, critical data not encrypted at rest.

• Weak password policies and non-rotated encryption keys.

And many more...

Malicious Code Evidence

When a software supply chain attack occurs, the bad actors may infiltrate malicious code and unintended behaviour, open backdoors and change the software in a way that could be used as a vector for malware delivery.

Malicious Code Evidence encompasses indicators of malicious software (malware) identified through static analysis of the target software. The integration of automated analysis tools for detecting potential supply chain breaches enhances traditional software security assessments. As malicious actors employ obfuscation techniques to conceal their modifications from manual reviews, these techniques can also provide further evidence of illicit activities.

From the evidence collected, a maliciousness score for the software under analysis is calculated. With enough evidence accumulated, the analyzed software could be classified as potentially malicious.

The Malware Scanner is a tool that checks the files of the software project under analysis, and reports "evidence" according to malware detectors currently active for the policy assigned to the project. Detected evidence could be uploaded to the Xygeni platform for consolidation and for enabling response actions.

Hardcoded Secrets

A secret in this context is any piece of information that allows an actor to gain access to a sensitive resource. Typical secrets are authentication credentials like usernames and passwords, API keys / tokens, cryptographic keys (symmetric or private), pass phrases, and many more.

Unauthorized access to sensitive information has led to significant disruptions in the software supply chain. Having hard-coded secrets in source code or configurations, particularly when under source control, is an invitation for bad actors to gain access to the organization’s sensitive resources.

Other types of information like personal or private information, business sensitive data, industrial footprints, etc... could be included in this category.

IaC Flaws

Infrastructure-as-Code or IaC is a method to provision and manage IT/Cloud infrastructure through the use of source code (IaC templates) under version control, rather than through operating procedures and manual processes.

An IaC Flaw represents a "flaw" or "defect" (a non-compliance) for a certain policy, found in an Infrastructure-as-Code (IaC) template.

Compliance failures

A Software Supply Chain Standard / Guideline is represented by a Xygeni Standard, which contains a list of Checkpoints. A Checkpoint is a requirement that the software must match.

A checkpoint may belong to a category. Categories break down a standard into a hierarchy of different areas that represent the standard’s relevant parts.

Each checkpoint could be required or optional. A required checkpoint is mandatory and must pass for the project to be compliant with the whole standard. An optional checkpoint, on the other hand, is evaluated but does not affect the global compliance status.

Checkpoints have further metadata, like the severity (which is the impact of a non-compliant checkpoint on the risk for supply chain security), what is the explanation of the checked condition, and what needs to be done for attaining full compliance (remediation).

When a standard’s compliance assessment is evaluated, a compliance report is generated, with each checkpoint result and a global compliance status.

The checkpoint result models the result of the evaluation of a checkpoint over the project under analysis. The result has a status (pass, partial, fail, n/a or unknown) with the following meaning:

• ok - The target project is compliant for the checkpoint.

• fail - The target project is NOT compliant.

• partial - The target project is partially (but not completely) compliant.

• n/a - The checkpoint does not apply for the target project.

• unknown - Checkpoint evaluation failed, result is unknown / inconclusive / uncertain.

The result indicates a compliance level on a scale from 0 to 10, where 0 denotes non-compliance, 10 represents full compliance, and values from 1 to 9 signify varying degrees of compliance.

The global compliance status is derived from the checkpoints evaluated, with this scheme:

• Optional and n/a checkpoints do not influence the standard compliance status, they are ignored.

• If no checkpoint was run, N/A is returned.

• Otherwise, if at least one mandatory checkpoint is non-compliant or unknown, FAIL is returned.

• Otherwise, if at least one mandatory checkpoint is only partially compliant, PARTIAL is returned.

• Otherwise, if at least one mandatory checkpoint is compliant, PASS is returned.

• If no mandatory checkpoint has a pass / partial / fail status, N/A is returned.

The global compliance level is the weighted average (with weights based on severity) of the compliance level of all the checkpoints evaluated (required and optional), with the same 0 to 10 scale, indicating how far the current status is from full compliance for the target software project.

Unusual Activity Events and Anomaly Detection

Unusual activity events represent user actions in your tools or over critical files that are out of the typical pattern of actions for the project.

The platform offers two main types of activity monitoring to detect and respond to potential security incidents or breaches: Critical file modification and User suspect behavior.

Critical File Modification (Code Tampering Prevention)

Xygeni provides vital capabilities to help organizations enforce security procedures and detect unauthorized changes on files marked as critical.

Our platform detects any change potentially leading to Code Tampering in these files when a commit does not match the conditions that must be accomplished for the changes to be accepted.

In such situations, the system launches an alert to notify the change on a subset of the project sources deemed as critical without following the prescribed change process.

Suspect Behavior (Anomaly Detection)

Xygeni’s policies and audit enforce best practices in access controls, multi-factor authentication requirements and role-based permissions applications to limit user access to critical systems and data.

Unusual activity detection performs continuous monitoring by collecting state changes from tools and logs and compiling usage patterns into a user behavior model.

After that learning phase, it identifies anomalies in new operations as deviations from the 'normal' user behavior modeled.

Live notifications for high-severity alerts are provided to the user, as this kind of flaw usually demands immediate action to mitigate the risk and prevent further damage.

Xygeni is a platform for improving the Software Supply Chain Security posture for organizations.

The platform protects the integrity and security of your software ecosystem throughout the entire SDLC by providing the following products:

Policies

A policy encompasses a comprehensive set of rules, procedures, checks, and processes designed to strengthen software infrastructure and mitigate the risk of supply chain attacks.

Each policy outlines acceptable and unacceptable behaviors, specifies required detectors, and details the impact based on risk scoring

A software project currently under analysis has an assigned policy, which varies in strictness according to the organization's criteria. The policy in effect is downloaded at scan time or when raw activity data is received from Xygeni sensors.

The Xygeni platform provides a default policy, tailored to cover a common assessment of the software supply chain security for most organizations.

The Dashboard pages are composed of three elements:

3. The actual page content.

Navigation Bar

The Navigation Bar lets you access all the Xygeni functionalities:

Projects Selector

The Projects Selector is a UI feature that allows you to select a project subset among the available ones in your Xygeni organization. The data on almost every UI page is associated with the selected project(s).

The subset of projects can vary from a unique project to All projects, passing for any defined subset.

To use the Projects Selector click on it and you can either select an specific Project or a Project group.

For pipelines or security policies that need specific rules or exit codes, complex conditions can be set using guardrail expressions.

The RL has the following properties:

• Issues with info and muted severity are ignored by the risk level calculation. They are just informative, and have no effect on the risk.

• A single critical issue makes the RL fall in the high risk range RL ≥ Ch; similarly, a single high severity issue makes the RL fall in the moderate risk range RL ≥ Cl. In accordance with the principle that "a chain is as strong as its weakest link," this holds true for issues within a project.

• Monotonicity: RL should increase when (non-info) issues are added. RL should NOT INCREASE when a single issue is removed. In other terms: if A1 and A2 are sets of issues with A1 ⊆ A2, then RL(A1) ≤ RL(A2).

  Also, if an issue changes to a higher severity, the RL should increase: more severe issues imply higher risk.

• No issues, No Risk: RL(∅) = 0. When no issues were detected but analyses were run, the risk level is 0. Note: When no analysis is available for a project, then RL is undefined, NOT zero.

• Averaged risk: For convenience, the RL for a group of projects, or for the organization could be computed using a weighted average on the RL of the projects.

Configuration

The relative weights for each issue type and severity, and the weight of each project in the global risk for the organization or project can be modified in the xygeni.risk-level.yml configuration file.

The cutoff values for each risk category can be configured as well:

# Configuration for risk level

# Weights for each issue kind and severity level
#
# Each array is the weight for issues of the given kind,
# with critical, high and low severity, respectively.
weights:
  misconfiguration:    [3, 2, 1]
  suspect_dependency:  [3, 2, 1]
  secret:              [3, 2, 1]
  iac_flaw:            [3, 2, 1]
  unusual_activity:    [3, 2, 1]
  code_tampering:      [3, 2, 1]
  sca_vulnerability:   [3, 2, 1]

# Cutoff values for each risk category [c_low, c_high]
#
# high risk, when risk level >= c_high
# moderate risk, when risk level in the [c_low, c_high) interval
# low risk, when risk level < c_low
#
# c_low must be lower than c_high, and both in the range (0, 100)
cutoff: [33.33, 66.66]

# The factor for normalizing the weighted count of issues
# into the risk range. Approximately the average
steepness: 0.00666

# Weight for risk level aggregation across projects.
# The business value project property is used for selecting the weight.
project_weights:
  critical:  4
  high:      3
  medium:    2
  low:       1

This screen enables users to:

• Review your organization's total projects count and their associated issues.

• View the list of projects scanned in the organizacion. The projects are ordered by last scan although the user can order them by other criteria clicking in the columns header of the table. For each project, user can see the branch configured as default in Xygeni.

• View the Security Posture for each project and a summary of issues by severity. Projects containing any type of malware are remarked with a special symbol (skull)

• Access to most usual actions related to projects with one click.

In this screen the Project Selector does not apply. The screen always shows all projects. The screen is shown and described in detail below:

Statistics

This section shows the number of projects scanned in the organization. Projects is a sum both of repositories and images scanned.

The following box shows a summary of total issues by severity in these projects. In the slide of detail of each project the user can check the stage of the SDLC in which Xygeni located potential malware and go to that section directly.

Filtering the list of projects

The user can customize the list of projects shown in the table applying filters:

• Alert: Filter by different types of alerts associated to the project as for example, containing malware. Only projects with that alert associated will be in the table below

• Project Type: to select projects of type ´Repository´ or ´Image Container´

• Name pattern: The table shows only projects with the string in the name

• Branch pattern: As the previous value, table only shows projects with the default branch containing the string in the filter

• Risk Level: Table consider only projects in the risk levels selected. Below you have more details about the Risk Score calculation and values.

• Tags: to show only projects with tags containing the string provided in this filter.

When any filter criteria is selected, the option ´Clear All´ over the filter boxes changes to red to indicate that a filter is active. Clicking on that option will reset all filters to the default settings.

Risk Score and Risk Level

The Risk Score (or Risk Level, RL for short) is a quantitative metric that assesses the current exposure to software supply chain attacks. It evaluates the security posture of the DevOps system based on scans conducted by the Xygeni platform.

The Risk Level is quantified on a scale from 0 to 100, with 100 indicating the highest level of risk. This measure is determined by the issues identified within a project. If no issues are detected, the Risk Level is rated as 0.

The RL is qualified in three categories that make more evident how good or bad is the risk for the organization. Each category is encoded with a color following the "semaphore" scheme:

• Low: RL between 0 and 33, green color.

• Moderate: RL between 33 and 66, yellow color.

• High: RL between 66 and 100, blood-red color.

Projects Table

Several details are shown in the projects table:

• Last scan date: The date of the latest scan for each project.

• Number of projects from the total items complying with the criteria of the filter.

• Bulk actions button: Only enabled once one or more projects are selected by clicking on their checkbox. Based on the projects selected, it will enable applicable operations.

You can interact with the rows in different ways:

• Clicking on a white space of the row, a slide with details about the project will open.

• Clicking on the 'scan now' button will launch an on-demand scan of the project.

At the end of each row, there is an icon with 3 dots that deploy a contextual menú for one-click access to different options.

Below you can find a quick description of the available actions:

• Scan Now: Launch an on-demand scan if the project is integrated in the managed scan system.

• View Details: Opens a slide with additional information.

• View Dependency Graph: If the user has the inventory license, the system shows the graphical representation of the project representing all assets with their security posture and the relationship among them.

• Download SBOM: Download the SBOM file in the selected format.

• Configure Project Settings: Only available for Root and Project Manager users. It opens the slide for configuration.

• Go to Repository: If detected, a new window opens to the project's repository in the corresponding Source Code Managemente system.

The Project Details (Slide)

Upon selecting the project's row or choosing the option to view details, a panel opens displaying multiple sections:

The Actions button on the top right area shows the same actions that the menu in each row described above.

Summary

The summary view of a project shows meta information related to the project date, size and location. The second section shows information about the team and the most active users. Some statistics from the languages contained in the project are also available.

Findings

Second section of the slide shows a detailed view of the issues found in each stage of the SDLC. Clicking on the name of the stage, the user will go to the specific list of issues in the corresponding product.

A special symbol (skull in this case) appears before the name of the section, if the system detects malware. Visiting the specific list of issues will show the malware as well as other vulnerabilities detected.

In the section below the statistics, you can directly see the first 5 issues of the category selected in the selector. For each issue, selecting the ´View Details´ option displays a panel with detailed information similar to that on the specific risks screen.

Integration Scenarios

Xygeni provides two main facilities for monitoring your build & deployment systems: a Scanner that runs on demand or when a certain event occurs, and connects to the target system for analysis. As well as a Sensor that is installed in the target system and notifies the Xygeni Platform when events of interest occur.

The following are the most common scenarios:

Using the Scanner Command Line

You may run a scan from the command line to analyze any local software project, a software repository, or a container image. The scanner discovers the assets and performs static analysis on the source code, package metadata and configurations.

The scanner runs scan steps aiming at each potential security issue class, and generates reports that can be uploaded to the platform.

To quickly access the Xygeni scanner after installation, execute the following command in the terminal:

# Scan a directory with software
xygeni scan --dir PATH/TO/PROJECT

# Scan a software repository
xygeni scan --repository URL

# Scan a container image
xygeni scan --image IMAGE

Integrate the Scanner into a CI/CD Pipeline

Integrating the scanner within a CI/CD pipeline offers a proactive approach, enabling the early detection of potential issues during the build and development process. This ensures problems are addressed promptly.

Under Continuous Integration / Continuous Delivery, an event on the source code repository often triggers a pipeline or workflow that builds, tests and performs different checks on the sources and the artifacts built. A Xygeni scan is an essential check, ensuring continuous monitoring of security issues that may compromise the software supply chain.

For streamlined integration, Xygeni provides facilities for integration into build pipelines for the primary CI/CD systems.

Running the Scanner as a Gate in a Git Hook

The Xygeni scanner could be run at client-side, before a commit is applied, by adding a pre-commit git hook.

If you have control over git hooks at your git server, you may add a pre-receive hook at server side, so a push may be rejected if the scanner finds critical security issues.

Two common use cases for such hooks are: avoiding secret leaks committed to sources and critical file modifications not following a required change protocol.

Using Sensors for Activity Monitoring

Unusual activity may indicate either a running attack or a sloppy change in the security configuration that opens the door to bad actors. To capture the activity as it happens in the software build & deploy systems, Xygeni provides a collection of plugins ("Sensors") that, once installed in the target systems, notifies to the platform the events of interest for correlation and identification of anomalies.

Live notifications for high severity alerts are provided to the user, allowing them to take immediate action to mitigate the risk and prevent further damage.

Uploading Findings from External Security Tools

Xygeni prioritization and response can also be used with security findings reported by other (open-source and commercial) third-party security tools.

The scanner provides a report-upload command for uploading the structured reports generated by third-party security tools, in areas like Static Application Security Testing (SAST), Software Composition Analysis (SCA), or Secret Leaks / IaC Flaws Detection.

In your CI/CD pipelines you may have a step where another SAST tool is launched to uncover vulnerabilities in your source code or configurations. The output of the tool could be ingested by Xygeni to normalize the findings, and then use the findings for prioritization and remediation.

The workflow accommodates findings from Xygeni scans and your preferred third-party tool, as long as its output format is supported.

Purpose

The Suspect Dependencies Scanner finds suspect dependencies (suspect deps for short) that may be the target of supply-chain attacks.

The aim is to detect potential flaws in the dependencies, direct or indirect, in the software project and DevOps tools around, so supply-chain attacks can be prevented.

Handling findings

Once a certain third-party component is known as malware, removing it for all software could be excruciating. Also, tracing what malicious code could have done in the exposure window between the component installation and its detection, often requires forensic analysis.

The detector documentation provides a Mitigation / Fix section that describes the recommended actions. Some reference practices that help to reduce the risk against dependencies-targeted attacks, like version pinning, using white-listed components from internal package registries, enforcing scoped internal components, or blocking installation scripts in package managers.

Quick Start

For detecting misconfigurations found in software project with sources in current directory, the command:

xygeni suspectdeps -n MyProject --upload

uploads the result to Xygeni platform.

For exporting the most important suspect dependencies to CSV for review, or importing the findings into another tool:

xygeni suspectdeps -n MyProject --detectors high \
       --format csv --output MyProject.suspectdeps.csv

Usage

The Suspects Deps Scanner is launched using the xygeni suspectdeps [options] command.

For a full reference of all the available option, you can issue :

xygeni suspectdeps --help

The most important properties are:

• Name of the project, -n or --name.

• Input, either a directory (-d|--dir) or a repository (-repo|--repository). If none is given, the local current directory is assumed.

• The JSON dependencies model generated from xygeni deps command could be used as input to the suspectdeps with the -r | --report option. If not provided, the dependencies model is extracted.

• Upload results to the service --upload. By default, results are not uploaded.

• Output file (-o or --output) and format (-f or --format). If no output file (or stdout / - are used), the standard output is used. Use --format=none for no output.

• The detectors to run could be tailored with the --detectors / --skip-detectors options. A common use-case is to consider only issues with high or critical severity with --detectors=high.

So, for example, setting --skip-detectors=steps_sbom,signed_commits will disable the two detectors.

Another use case is to disable issues with info / low severity (--skip-detectors=low) or equivalently enabling only high or critical issues (--detectors=high).

Xygeni's Prioritization Funnels enhance your ability to filter and identify crucial issues, enabling you to focus on resolving the most significant matters.

Given a full set of security issues, Prioritization Funnels allow you to specify the “prioritization criteria” that will be automatically applied to the full set of issues, discarding the issues that don’t meet the criteria. The resulting set will contain the most important issues to remediate.

Xygeni’s Prioritization Funnels are available for any kind of security risks and are available under the All Risks section and selecting on the Prioritization funnel button .

The main funnel (feed with all types of risks) is available at All Risks menu option (at the top-left). But you can also find risk-specific funnels under any “Risk” option in the different products available at the left-menu (SAST), SCA, CI/CD) security, Secrets, Infrastructure as code, Malware, Build Security and Anomalous Activity) .

Out-of the-box Funnels

Xygeni comes with some out-of-the-box predefined Funnels

In the filters of any funnel, click on the “Funnel” filter and the available funnels are displayed:

• ** Xygeni General Prioritization

• ** Xygeni CI/CD Prioritization

• ** Xygeni IaC Prioritization

• ** Xygeni SAST Prioritization

• ** Xygeni Secrets Prioritization

The funnel will be displayed based on “Severity” by default. By clicking on the “Split by” filter, you can make the funnel to be based on several categories (Malicious Code, IaC, Secrets, CI/CD, Open Source, etc) as well as severity.

How to see the specific issues filtered by the funnel criteria ?

At the bottom of the page, there is a filter box where you can select which issues you want to see.

Funnel Phase, allows you to filter by any specific funnel criteria. If you select any of them, the issues list will contain the items filtered until the selected criteria

Once you select on a funnel phase, the table will show the issues contained in the selected phase. You can further refine your search by selecting additional filters.

Reachability

When a dependency has a vulnerability (i.e. a CVE), is that CVE really affecting my application?

Reachability, in a SCA (or vulnerability analysis) context, is a property of a vulnerability finding that indicates whether it will (or wont) be invoked under the software’s normal operational conditions.

Analyzing the reachability for a large set of vulnerability findings for a software is important.

Most of the SCA scanners work by extracting the dependency graph (direct and transitive/indirect dependencies) from manifest files (pom.xml, package.json etc.), and simply enumerate the known vulnerabilities that are listed in vulnerability databases (NVD and others). This gives many more findings that the real vulnerabilities that a potential adversary could exploit in the deployed software.

Most of those findings are NOT actually reachable, because although the dependency with the vulnerability is “imported” (in the component descriptors of the target software S and transitively on its dependencies), your application only uses a small portion of those components, not invoking the vulnerable code of the dependacny.

By focusing on reachable vulnerabilities only, the ones that exist within the code usage path of S, we focus on the vulnerabilities that can pose an actual risk. By doing so, we disregard the ones that, while present, may never be executed.

Values for Reachability

• Reachable: An issue is flagged as reachable when the application's call graph can access the vulnerable method in the dependency, either directly or indirectly.

• Always Reachable: If an issue is flagged as always reachable, it is strongly recommended that the vulnerability be fixed regardless of your application code. This often occurs when the vulnerable part is unrelated to a specific dependency method.

• Potentially Reachable: An issue is flagged as potentially reachable when it's impossible to confirm its reachability or unreachability. Common reasons for this include unsupported call graph analysis for certain languages or package managers, insufficient information, and scenarios with dynamic or conditional invocations.

• Not reachable: An issue is flagged as not reachable when the application's call graph analysis determines that no function calls directly or indirectly invoke the vulnerable method in the dependency.

Fixable, (at least in OS depedencies) meant that, for a certain vulnerability in a version of a dependency, there exists a further version that fixes the vulnerability.

Because there is not always a fix available, Fixable can take different values:

• No Fix Available : There does not exist any version that resolves the vulnerability.

The Xygeni platform is a cloud-based service, accessible via REST API, that keeps findings and metadata from different sources.

The Xygeni platform is represented by the chart below:

Scanner

Dashboard

Trends exploration, reporting, and platform administration, among other facilities are also displayed.

Rest API

Integrations

Xygeni provides integrations for running scans or uploading security issues, performing administrative operations, or exporting findings to communication and reporting tools.

Sensor

Activity on public repositories is monitored by Xygeni so potential attacks could be detected early. Publishing new packages in popular public repositories is an example of an activity that is monitored by Xygeni. In addition, security advisories are ingressed for modelling new threats and malicious activity on the wild. Xygeni customers may receive alerts when a security issue may affect them.

You can create your own Custom Prioritization Funnels.

Then, you can either create a New Funnel, Clone the selected funnel or Delete the selected funnel.

Click on New Funnel and give the funnel a name.

You can also use this new funnel as a “default” funnel for whatever type of risk.

After naming the new funnel, you can add the criteria by selecting among the available ones in “Select a stage to add” .

Once you select one, click on the plus + sign to add it to the funnel.

You will see some values for the criteria (true or false in this example). You can decide which value must be met by any issue to “pass” the criteria. For example, selecting Reachability: true, means that any reachable issue will pass this stage of the funnel.

You can add as much criteria (or stages) as you want, but remember that order is important. Criteria is applied from top to bottom. You can drag-and-drop the criteria to change their order.

For multi-valued criteria, selecting several options works as an “OR”.

When done, click on Save button and your new funnel will be displayed and among the available ones.

Guardrail Specification

When specific rules or special exit codes are required by pipelines or security policies, complex conditions can be defined using guardrail expressions.

Guardrails enables users to customize and specify how a Xygeni command should behave in the presence of certain conditions or criteria, thereby allowing for flexible and tailored handling of failure scenarios.

Guardrail specification is a subset of Xygeni™ XyFlow Language, tailored for guardrail conditions.

Exploitability

Given we found an issue with a CVE, we should first know if it is reachable (as seen above). But even when reachable, what is the likelihood to be exploited?

We’re continuously drowning in CVEs — including many high-severity CVEs — but the majority aren’t actually exploitable. This, of course, can make it difficult to prioritize vulnerabilities as well as to estimate remediation efforts.

CVEs provide a “metric” for such exploitability (based on CVSS). CVSS scores vulnerabilities based on their characteristics and potential impacts but don't consider real-world threat data. Conversely, EPSS forecasts rely on up-to-the-minute risk intelligence from the CVE repository and empirical data about real-world system attacks.

While CVSS measures the inherent (theoretical) severity of vulnerabilities, EPSS predicts the likelihood of exploitation based on empirical data.

In this context, although Xygeni scores the severity of a CVE issue based on CVSS, the Exploitability criteria adds a more reliable criteria to the funnel, thus filtering out those issues with low exploitability likelihood.

You can view the EPSS Score associated with a vulnerability in the Vulnerability Details section.

Trends Page

Trends page shows governance information about issues discovered, remediation, trends, etc.

It can be accessed through Reports >> Trends at the Menu Bar.

Overall Metrics

Top panel shows different metrics by "period" (last month, last 3 months, last 6 months and last year)

• Total Issues is the number of Total Open issues at present date.

• New Issues is the number of New Issues (i.e. opened) at present date.

• Exposure Window is the elapsed time between the creation of an issue and present date (this metric only applies to open issues). Mean Exposure Window is the arithmetic mean of all the open issues' exposure window.

• Time to Resolve is the elapsed time between the creation and closing of an issue (this metric only applies to closed issues). Mean Time to Resolve is the arithmetic mean of all closed issues' time to resolve.

Cumulative Pending Issues

Cumulative Pending Issues chart shows information about evolution of issues.

Being X-axis the timeline of the select period, left Y-axis indicates the Number of New / Resolved issues and right Y-axis indicates the Number of Open issues.

Impact of Anomalous Activities

Impact of Anomalous Activities chart displays information about frequency of anomalous activities (Critical File Changes and Suspicious Activity)

Issues Exposure Window

Issues Exposure Window chart displays information about the number of issues at a certain date falling into three Exposure Window thresholds (<15d, 15-30d and >30d)

Issues Time to Resolve

Issues Time to Resolve chart displays information about the number of issues at a certain date falling into three Time-To-Resolve thresholds (<15d, 15-30d and >30d)

Metrics by Group

Metrics By Group table displays metrics for a group of projects. Grouping is based on Projects' Properties. You can select the grouping property and it will display all the property's values with metrics of all the corresponding projects.

SCM CI/CD Systems

Xygeni can be integrated into most SCMs and CI/CD systems.

Here are examples on how to integrate Xygeni into several SCMs and CI/CD systems:

Sensor Plugins

Xygeni allows you to actively monitor and address vulnerabilities as they are detected in the SCM or CI/CD systems.

Below are the listed sensors applicable for SCM and CI/CD systems:

Git Hooks

Xygeni seamlessly integrates with Git Hooks.

Ticketing and 3rd Party Platforms

Xygeni allows to create tickets, issues and alerts in the following platforms:

Collaboration & Communication Tools

Xygeni allows to configure notifications in the following platforms:

Remediation (auto-fix)

Xygeni allows automatic fixing of certain types of issues in the following platforms:

At Home >> Scan History, you can access all the historical information related to executed scans.

The Top panel shows a timeline of the frequency of the scans, splitted by:

In case of error or warning, the slide will display the reason(s):

The list of scans also show (and filter) the scope of the scan: complete (Full Scan) or partial (Partial Scan)

Scans Comparison

Most of Risk pages contain a functionality to compare scans. It can be accessed by selecting ChangeLog option.

Xygeni allows to generate a SBOM for a certain project.

Two SBOM formats are currently supported:

You have two options to generate an SBOM:

Generate a SBOM from the Web User Interface

Once you have selected a project, the Dashboard will present you the Download SBOM option.

You can also open a project's detail slide to download the SBOM.

Generate a SBOM with the Xygeni CLI

You can also generate a SBOM with the xygeni CLI. This is useful if you need the SBOM during a build/deploy CI/CD process.

Reports section can be reached from Report at the Menu Bar, and contains following pages

• Governance information about issues discovered, remediation, trends, etc.

• Historical information related to executed scans

Organizations may need to customize the Xygeni platform to meet their specific needs. Although Xygeni is designed to provide useful, actionable findings on the security posture of an organization against software supply chain attacks from the very start, Xygeni also provides a rich REST API and a set of development tools for special customizations.

API

Custom Detectors

A Xygeni detector is a piece of logic that detects a security issue in a scanned target system such as source code, a source code repository or a container image, a CI/CD system or other software too.

Xygeni provides a rich set of predefined, off-the-shelf detectors used in scans, although you may add your own custom detector. Such custom detectors can be easily integrated into scans using the --custom-detectors-dir option.

Defining Custom Converters for 3rd-Party Tool Reports

Xygeni provides a framework for developing customized report converters and registering them so they are available in the report-upload scanner command.

All Risks page

Regardless you have selected one single project or a group of projects, All Risks page presents three different views:

The 'All Risks >> Statistics' view shows relevant data such as:

• The total number of issues displayed by type & severity.

• A table displaying these issues.

You can see issues of a specific type by clicking on each type:

You may also filter these issues by the following criteria:

• Severity

• Explanation

• Issue Category (cicd, iac, secrets, etc...)

• Issue Type

• Project (pattern)

• Issue Status (open, confirmed, muted, etc...)

• Tag

Xygeni’s Application Security Posture Management (ASPM) tool enhances how your teams visualize, prioritize, and remediate risks. The Xygeni platform delivers real-time visibility and contextualization that simplifies security, ensuring your applications are protected from development through deployment.

Automated Asset Discovery and Inventory Management

Xygeni provides automated solutions for comprehensively identifying and cataloging assets within your software supply chain, enhancing visibility and control over your development and deployment processes.

Furthermore, Xygeni automatically identifies and continuously monitors these assets, assessing their interdependencies as well as the individual and overall security posture of each asset, application, and customer defined group or category.

Users and Contributors Analysis

This analysis is essential for the effective management of administrative users, contributors, and collaborators associated with software repositories. By monitoring user activity and evaluating each user's role, we can ensure we follow best practices and resolve these issues as soon as posible.

Xygeni also helps organizations implement a least privilege strategy by identifying risks associated with inactive or overprivileged users.

Some key features are:

Advanced Dynamic Prioritization

Customers can define up to eight stages in their prioritization funnel. Tailored by severity, issue type and category. This flexibility ensures that each organization can focus on the vulnerabilities that pose the highest risk according to their specific security policies and operational needs.

The funnel system supports the integration of customer-defined properties alongside pre-configured stages such as reachability or exploitability, among others. This allows organizations to further refine their security focus and manage vulnerabilities more effectively.

Integration of 3rd-Party Security Reports

Xygeni’s Application Security Posture Management (ASPM) platform can also seamlessly integrate reports from third-party security tools, including Static Application Security Testing (SAST) and Software Composition Analysis (SCA) tools.

This capability enables organizations to optimize their current technology infrastructure. Offering a unified perspective on security threats across various tools and platforms ensuring that all potential vulnerabilities are identified, prioritized, and addressed efficiently.

Key benefits of this integration include:

• Unified Security Dashboard: Consolidates findings from various tools into a single dashboard for monitoring and analysis.

• Enhanced Threat Detection: Combines data from multiple sources to provide a more complete assessment of security risks.

• Efficient Remediation: Enables quicker and more coordinated responses to security issues by centralizing vulnerability management.

Audit Trail of Security Events

Xygeni’s Application Security Posture Management platform includes a robust security audit trail feature that provides a comprehensive timeline of events associated with each asset.

This feature tracks and logs all significant activities, such as changes, updates, and security incidents. Ensuring that users have a clear and detailed view of the security history for each asset within their software environment.

Some notable capabilities of our security audit trail feature are:

• Event Log: Every modification, update, or security event related to an asset is logged. Creating a chronological record that can be crucial for troubleshooting, compliance audits and security investigations.

• Comprehensive Coverage: The audit trail captures a wide range of events, from code commits and build configurations to deployment activities and configuration modifications, ensuring that all aspects of the asset lifecycle are monitored.

• Effortless Access and Visualization: Users are able to efficiently access and visualize audit trails, facilitating the identification of specific events or patterns.

• Enhanced Security and Compliance: By maintaining a detailed record of all actions taken on each asset, Organizations can strengthen their security framework and ensure adherence to regulatory standards, facilitating the verification of procedural compliance and enabling the early detection of a security breach.

Quick and Efficient Remediation Process

Xygeni’s ASPM platform optimizes the remediation process by providing detailed guidelines and automated actions for addressing each risk and vulnerability.

Integration with ticketing and tracking systems streamlines the process of updating workflows, ensuring that vulnerabilities are promptly addressed.

By selecting Issues Evolution on the All Risks page, you can see the evolution of the issues by type. You can also specify different time frames (last month, last 3 months, etc...)

Xygeni's ASPM section comprises of four primary tabs:

The following sections describe the key elements within the Xygeni Platform.

Most of the Risk pages contain a functionality to compare scans. Accessed by selecting ChangeLog option in these Risks pages.

To compare two scans, you must select the source (FROM) and the target (TO) scans

The source scan (FROM) allows to be selected among:

• Pre last scan (the previous to the last executed scan)

• First Scan (the first scan of the project, by default it's the project baseline)

• A specific scan (selected by execution timestamp)

The target scan (TO) allows to be selected among:

• Last Scan (the last executed scan of the project)

• A specific scan (selected by execution timestamp)

You can filter the list by type of change (new and/or removed)

The All Assets page shows the full list of assets for a given project or for a set of projects.

Given the wide variety of asset types, the top side bar categorizes related assets into several groups.

• Repositories

• Images

• Components

• CI/CD Assets

• Delivery Assets

• Systems and Tools

• Collaborators

The All Assets page displays the following information:

• Number of Assets

• Number of Assets at Risk. (i.e. with security issues)

• Number of systems and tools

• Charts displaying total issues by severity, category and category & severity. (With links to specific assets types)

• A table with all the assets with some basic information:

The information for each asset:

• Risk level

• Variation of the Risk Level from the project baseline

• Name

• System

• Category

• Asset type

• Issues by severity

• Tags

• Links to details of the asset

Pivot Graph

The Pivot Graph shows the direct relationships with other assets.

Assets marked with a red circle and a number denote the associated security risk level, indicating potential security threats related to that asset.

Clicking on them displays the details of the asset alongside its issues.

Findings and Audit Trail

You can also select the Audit Trail tab to see a timeline of all the security issues.

The Components Inventory page displays information about all the components (3rd party dependencies) your project or group depends upon.

The Components Inventory page displays the following information:

• Total number of components and average per project

• Total number of Direct dependencies (i.e. those explicitly declared in your package manager's manifest files)

• Number of components with security risk associated

• Charts about the distribution of components by repository, ecosystem and language

• A table with listing all the present components

• Ecosystem (npm, maven, etc)

• Provenance (the parent component in case of a transitive dependency)

• Data about the publisher of the component

• Malware Score

• Latest available version and publication date

• License detected and type

The Issues tab shows information about vulnerabilities of the component.

The CI/CD Assets Inventory displays information about CI/CD assets of your project(s), including:

• Pipelines

• Jobs

• Build Scripts (makefiles, pom.xml, etc)

• Scripts (shell scripts)

The CI/CD Assets Inventory page displays the following information:

• Total number of CI/CD assets (and number of assets with security issues)

• Distribution by type

• CI/CD systems detected

• A table with a full list of all the CI/CD Assets

Steps to address a security incident or vulnerability

The documentation for each detector provides examples for addressing specific security issues, as well as recommended procedures for assessing the impact and resolving the issue.

Remediation Actions

Examples of remediation actions include revoking leaked secrets, modifying infrastructure playbooks or receipts and updating existing resources, hardening authentication or authorization settings for CI/CD tools, or fixing pipeline configurations.

Automatic Remediation

Xygeni provides mechanisms to automatically remediate certain kind of issues.

Handling Actions in Xygeni Dashboard

• Manage Issue: A basic handling workflow, for setting a status.

• Create ticket: Opens a new ticket in the configured ticketing tool. Full information for the issue is rendered so the ticket can be created with minimal work.

• Open Pull Request (PR): Opens a pull request in the configured Source Control Manager, with contextual information on the issue. Commits with changes in source / configuration files can be added to the branch, for automation, so after review the pull request can be approved for merging into the target branch.

• Disable Check: Deactivates the detector that reported the issue, possible for all the policies including it. This action is only available when the user’s roles allows it. This is a quick way to remove detectors that do not apply for the organization, or that are creating issues that should be ignored systematically.

• Search Similar: Opens a view with issues similar to the selected one. Similarity is typically by the specific issue type across all projects. This helps to focus on fixing all of them by applying the recommended fix steps.

Internal Issue Management

The Xygeni platform provides a basic handling workflow that helps to trace each issue.

The Status field may take the following values:

• Open: The initial status: The issue has not yet handled.

• Under review: The issue is under investigation.

• Confirmed incident: The issue is a confirmed security problem, and should be fixed.

For unusual activity, additional states are available:

• Incident closed: The problem was corrected, and any potentially harmful consequences related to the unusual activity were handled.

• Normal business: Internally the issue will be "muted", applying to current issue and current scan.

Only for security issues (secrets, misconfigurations, bad components and IaC flaws):

• Muted: False Positive The issue is not legitimate. To report this as a bug, check "Create false positive ticket for Xygeni" to open a support ticket.

• Muted: Accept the risk. The issue is acknowledged, but the risk is assumed instead of trying to fix the issue.

• Muted: Other. When the issue needs to be silenced for other reasons.

To change it for a given security issue, just open the issue and click on "Change Status" (see image below)

Then, a dialog will open where you can the change the status as well as provide any further additional information about the reason of the change.

To change the status of several issues (bulk mode) at once: First, select the checkbox on the left on each issue you want to modify. Then, under the 'Actions' tab select the"Change Status" option.

The SDLC Inventory provides a comprehensive perspective on risk propagation throughout systems and highlights potential attack vectors that may impact other entities. It enables the identification of secure and vulnerable pipelines, and offers insights into the components involved in software build and deployment processes.

The Asset Graph

It is important to understand the different types of assets used within the SDLC Inventory and their relationships:

• Repositories may contain children (modules), each with its own dependencies graph. Many repositories are single-module, anyway.

• A module refers to a dependencies graph, and may produce one or more build artifacts (libraries, container images…​), that could be published in component registries.

• A repository is often built by a CI/CD product, using one or more build workflows. (a build workflow may build artifacts from multiple repositories and publish the artifacts in different registries, i.e. a real graph).

• Sometimes the pipelines are files under version control along with the repository. Some SCM systems enforce this pattern within their CI/CD systems. As well as other external CI/CD tools like CircleCI also, but others like Jenkins do not.

• The CI granularity also has various levels. For most CI/CD systems, a 'build pipeline' for a project has 'workflows', each workflow has multiple jobs, and 'jobs' (which can run in a given build machine or an "array" of them) is a sequence of 'steps' or 'commands'. The graph can fully represent this hierarchy or not (keep at a given level of granularity, like the workflow), but at the end the real build commands run are those little steps at the end.

• On the contrary, a CD pipeline is built from IaC configuration files (a set of IaC template files under a given framework like Terraform, Azure ARM or Bicep, AWS CloudFormation…​) which specify commands to sync the desired state represented by the IaC configuration with the existing assets in the cloud. So the CD pipeline may have multiple workflows based on jobs that run the tool’s CLI command (terraform, aws, az, ansible) to perform the sync or build the assets directly.

There are "contain" dependencies (a "parent" node can break down into "children") and "uses" dependencies ("builds", "runs", "publishes", "deploys"…​) that could be represented by the directed graph.

Asset Discovery

Prioritization Criteria (Stages)

Any funnel is composed of criteria that produce the different stages of the funnel.

Out-of-the-box criteria

Xygeni provides several out-of-the-box criteria, although you can add your own custom criteria.

Criteria's Specifics

Additionally to the general meaning of the above prioritization criteria, every criteria has a special meaning depending on the issue type that applies.

Custom criteria

Besides the above out-of-the-box criteria, you can create your own custom criteria. To do it, you just need to add custom properties to your applications (projects in Xygeni’s terminology) and those properties will be available as funnel criteria.

The Systems & Tools Inventory displays information about systems and tools used in your project(s):

• Security tools used in your pipelines (bandit, checkov, Checkmarx, Sonarqube, etc...)

• SCMs (GitHub, Bitbucket, etc...)

• SCM plugins

• CI/CD systems (GitHub, Jenkins, Tekton, etc...)

• CI/CD plugins

The Systems & Tools Inventory page displays the following information:

• Total number of System & Tool assets and number of assets with security issues associated.

• Distribution Systems & Tools by type

• Distribution of security tools by type

• A table with a full listing of all the Systems & Tools

Report Upload

The report-upload command allows you to import findings from both third-party tools and Xygeni scans into the Xygeni platform.

The command validates reports, normalizes findings, and converts them to the Xygeni standard format. It processes findings from different tools for prioritization, filtering, workflow, and remediation. The converted output can be optionally sent to the standard output or saved to a file for validation or baseline generation.

The syntax is:

xygeni report-upload
  [--show-formats]
  [--directory=<path>] [--name=<name>]
  [--prop=name:value [--prop=name:value]...]
  [--never-fail] [--[no-]upload]
  --report=<file> [--format=<format>] [--log-file=<logFile>] [--output=<output> [--compact]] ...
   [@<filename>...]

Converts and uploads an external tool or xygeni scan reports into Xygeni platform.

Parameters:
      [@<filename>...]       One or more argument files containing options.
  -s, --show-formats         Show the formats supported.
  -n, --name=<name>          The software name. Inferred from directory when not provided.
  -d, --basedir=<path>       Base directory for resolving relative paths.
                             Default is the current working directory.
  -p, --prop=name:value      Properties for the software.
                             Name of standard properties are: business_value (or bizval), architecture (or arch),
                               business_area (or bizarea), product_unit (or product), and provider.
                             business_value should be one of: CRITICAL, HIGH, MEDIUM, LOW, INFO.
                             Additional custom properties may be added.
      --never-fail           Do not fail: always exit with code 0, even when report conversion or upload fails.
      --[no-]upload          Upload reports to server? (default: true}
                             Use --no-upload for testing report conversion.
Reports to upload:
  -r, --report=<file>        the report file to upload. Use '-' or 'stdin' for standard input.
  -f, --format=<format>      the format / type of the report to upload.
                             Use <tab> to get the available values, when autocomplete is active.
                             Optional. When not given, it will be inferred from the report.
  -o, --output=<output>      file for writing the output in Xygeni format.
                             Use '-' or 'stdout' for console output.
                             Optional. No output when not given.
      --compact              Use compact output (default: pretty-print).
  -l, --log-file=<logFile>   The xygeni scan logfile to upload (optional).

To list the supported third-party tools and formats supported, run xygeni report-upload --show-formats

The -n | --name option provides the project name the reports uploaded will be assigned to. It will be inferred if not provided. For a single xygeni report it will be extracted from the report metadata.

Multiple reports can be provided, so the -r|--report, -f|--format and -o|--output could be given in triples. Only -r|--report is required, the other flags are optional.

The -l|--log-file only will be used for xygeni scan results and will be ignored otherwise.

The scan logfile could be optionally uploaded to Xygeni, using the --log-file parameter.

The command returns 0 (OK) exit code when the upload succeeded, or a non-zero exit code when there is an error. When the upload is successful, the scan code is printed as the output of the command.

The command exits with 0 (OK) when the upload is successful, or with a non-zero exit code if an error occurs. After a successful upload, the command will output the scan code.

Examples:

• List the supported formats:

xygeni report-upload --show-formats

• Upload a Checkmarx SAST report (xml format):

xygeni report-upload --name=MyApp --format=sast-checkmarx --report=rep/checkmarx.SAST.xml

• Upload two previously generated xygeni reports:

xygeni report-upload -n MyApp \
       -r rep/xygeni.deps.json -l=rep/xygeni.deps.log \
       -r rep/xygeni.secrets.json -l rep/xygeni.secrets.log

• Convert snyk report into xygeni, but do not upload. This could help to check the conversion performed before set in the CI/CD pipeline.

xygeni report-upload -n MyApp -r rep/snyk.json -f sca-snyk -o xygeni.sca.json --no-upload

• Upload SCA, SAST and IaC findings from Checkmarx One report exported using cx results show command:

xygeni report-upload -n MyApp \
  -r rep/cxOne_results.json -f sast-checkmarx-one-results \
  -r rep/cxOne_results.json -f sca-checkmarx-one-results \
  -r rep/cxOne_results.json -f iac-checkmarx-one-results

You can reach the Repositories Inventory page either by selecting Projects in the top tab of the Inventory page.

The Inventory Projects page contents are different depending on if you have selected a group of projects or a single project.

Group of Projects

For a group of projects, the page shows:

• Total number of projects in the group

• Number of files and total size of the group

• Number of commits and daily rate

For every project, it also display information about the number of issues by Asset Category (coloured by highest priority with issues)

For each project, detailed information regarding the number of issues organized by asset category is provided. Highlighted by the highest priority in a corresponding color scheme.

The other tabs (SCM, Package Manager, CI/CD, AppSec and Deploy) show the project's assets by category.

Selecting a single asset will show additional info about the asset as well as assocaited security risks.

Single Project

• Number of files and size

• Number of commits and daily rate

• Creation date, last code change, etc

• Team and Contributors of the project

• Programming languages

The bottom panel shows aggregated information about the assets of the project.

Inventory (Panel and Slides)

The bottom panel of the Repository Inventory page for a single project shows data about the assets of the selected project, grouped by:

• SCM (repository platform, issues by severity, # of commits)

• Package Manager (pkg managers used by the project, # of packages, issues by severity)

• CI/CD (CI/CD platform, number of pipelines, number of plugins, issues by severity)

• AppSec (appsec tools used, etc)

• Deploy and provisioning (cloud platforms, number of cloud resources defined in IaC files, issues by severity)

By clicking on a specific asset you will see the details of that asset:

Inventory (Dependency Graph)

Accessing the Dependency Graph will present a comprehensive visualization of all assets and their interconnections within the selected project. Utilize the available filters to refine the diagram according to your requirements.

Select an asset to view a detailed slide:

Download the SBOM

Selecting "Download SBOM" allows to generate and download the project SBOM in Cyclon DX or SPDX formats.

The Inventory Scanner is configured in the YAML file conf/xygeni.inventory.yml.

The file contains properties to specify:

• Files to include/exclude. Defaults are provided for common directories to ignore.

• Configuration for report output, including the columns/fields to render.

• Configuration for each ecosystem analyzer.

• Scan configuration properties like mode = sequential or parallel. Parallel model utilizes threads to run the scan in parallel across files and detectors.

# Configuration for xygeni Assets Inventory scanner.
# Arguments from command line have priority over properties in this file.

# Includes: list of glob patterns to include in analysis.
#
# A pattern could use ** (to match zero or more directories), * (zero or more characters
# in a directory or file name), and ? (one character).
# Examples: **/*.txt matches all files with 'txt' extension. **/test/** matches all files under any test directory.
#
# If empty, ALL files will be matched.
# The command-line argument -i or --include will be used when specified.
#
# A file is analyzed when matched by 'includes' AND NOT matched by 'excludes'.
includes: []

# Excludes: list of glob patterns to exclude from analysis.
# If empty, NO file will be excluded.
# The command-line argument -e or --exclude will be used when specified.
excludes:
  - ".git/**/*"
  - ".vscode/**/*"
  - "build/**/*"
  - "dev/**/*"
  - "**/__pycache__/**/*"
  - "**/.eggs/**/*"
  - "**/locales/**/*"
  - "**/spec/**/*"
  - "**/specs/**/*"
  - "**/test/**/*"
  - "**/tests/**/*"
  - "**/mock/**/*"
  - "**/mocks/**/*"
  - "**/integration/**/*"
  - "**/node_modules/**/*"
  - "**/bower_components/**/*"
  - "**/.xygeni.*.json"
  
# mode=sequential runs analyzers sequentially;
# mode=parallel runs analyzers in multiple threads, when analyzer is capable of parallel runs.
mode: parallel

# Timeout, in seconds, for the analysis to complete. 0 or negative means no timeout.
timeout: 600

# Config for reporters
report:
  - format: json
    prettyPrint: true

  - format: csv

    # Allowed values: "id", "kind", "scope", "name", "qualifiedName", "belongsTo", "fullyResolved", "path", "createdAt", "updatedAt", "tags", "properties"
    columns: [ "kind", "name", "qualifiedName", "belongsTo", "fullyResolved", "path", "createdAt", "updatedAt", "tags", "properties"]

    # Order specification. 'default' lists by kind first, then by name.
    # One of 'default' or 'id'.
    sort: default

  - format: text

    # Allowed values: "id", "kind", "scope", "name", "qualifiedName", "belongsTo", "fullyResolved", "path", "createdAt", "updatedAt", "tags", "properties"
    columns: [ "kind", "name", "belongsTo", "tags" ]

    # Order specification. 'default' lists by kind first, then by name.
    # One of 'default' or 'id'.
    sort: default

    # The style for table borders.
    # One of 'full', 'none', 'outside', 'inside', 'horizontal', 'vertical', 'topbottom'.
    # Use 'default' for border that works well for the underlying OS.
    borders: full

    # The block characters to use: 'ascii' (use '+', '|', '-' and '=')
    # or 'utf8' for UTF-8 block characters.
    # Use 'default' for the encoding that works best for the underlying OS.
    bordersEncoding: utf8

# The detectors to use for discovering SDLC assets
# are configured in resource files under inventory/*.yml

# List of detectors to run: IDs.
# Leave empty for no restriction (all detectors not disabled will be chosen).
# Command-line property --detectors overrides this.
runDetectors: []

# Same format as runDetectors, but for skipping the selected detectors.
# Leave empty for no restriction (all detectors not disabled will be chosen).
# Command-line property --skip-detectors overrides this.
skipDetectors: []

Inventory Assets Detectors Configuration

Assets from various ecosystems are managed by each designated detector. These detectors handle relevant files and other sources, and can invoke an API, if available, to gather more details about the asset.

The following ecosystems are supported:

• Source Code Management (SCM) systems: GitHub, Azure Devops, BitBucket, GitLab.

• Dependencies Management systems for multiple language ecosystems, including Package managers and Component Registries like NPM, Maven, Gradle, Bower, Nuget, pip, go.mod, RubyGems, PHP Composer, Swift Package Manager, CocoaPods, Carthage, Cargo, etc.

• CI/CD tools: The systems provided by the SCM systems listed above plus specialized CI/CD systems like Jenkins, CircleCI or Travis CI.

• Security tools: A variety of security tools, configured in the xygeni.security_tools.yml file.

• Cloud assets include technologies like containers, container orchestrators, and Infrastructure-as-Code (IaC) frameworks. Examples are Dockerfiles, docker-compose, Kubernetes, Terraform, Bicep, Azure Resource Manager, CloudFormation, and Ansible.

About

Kiuwan is a powerful, end-to-end application security platform. Kiuwan Static Application Security Testing (SAST) product is the tool that detects security vulnerabilities in source code using static analysis.

The problem is that Xygeni does not provide a mechanism in the agent (Kiuwan Local Analyzer) for writing to a local file the findings from the tool.

How report extraction works

The Kiuwan scanner (Kiuwan Local Analyzer) by default uploads its findings to the Kiuwan platform.

Steps

1. Compile the extraction rule (optional)

2. Install rules and jar file

Once rules and jar uploaded and added to the Kiuwan model, the local analyzer will execute the exporter rule when the output report is given, so it can be uploaded into Xygeni.

3. Run the scan

Run the Kiuwan Local Analyzer with the path to the report file provided in the KIUWAN_JSON_REPORT environment variable.

4. Upload the Kiuwan report to Xygeni

Use the xygeni report-upload command for uploading the exported report, after normalization to the Xygeni SAST format.

The Health Check page displays useful metrics and details about your Xygeni projects.

There are several sections within the Health Check page:

Findings by Category

The Findings by Category chart shows a 5-axis spider chart where there is a relevant score for each axis.

Projects

The Projects section displays two types of information:

1. Inactive Projects, i.e. xygeni projects whose last code change is older than XXXX (TBD)

If you click on the Inactive View >> link, you will see the inactive projects as well as the applied filters:

1. Obsolete Branches, i.e. repository branches whose last code change is older than XXXX (TBD)

If you click on the Obsolete Branches View >> link, you will see the inactive branches as well as the applied filters:

Components

The Components section displays several types of information related to your components.

Licensing Issues refers to the number of components with some kind of issues related to the component's license (mainly, use of a copyleft license).

With different versions refers to the number of components that are used in 2 or more different versions.

Out of date Versions refers to the number of components that have a new version is available.

Obsolete components refers to the number of components whose newer version is older than XXX (TBD), possibly meaning that those components are abandoned or out of maintenance and you should consider using another component.

If you click on any of the View >> links, you will see the components as well as the applied filters:

System and Tools

The System and Tools section displays your SCM system, build/cicd tools.

Collaborators

The Collaborators section displays two types of information:

1. Inactive Collaborators, i.e. repo users whose last activity is older than XXXX (TBD)

If you click on the Inactive View >> link, you will see the inactive projects as well as the applied filters:

1. Over-privileged Collaborators, i.e. users whose actions performed do not need granted permissions (TBD)

If you click on the Over privileged View >> link, you will see the over privileged collaborators as well as the applied filters:

Pipelines

The Pipelines section displays information about the total number of pipelines and how many of them are inactive (i.e. not executed in the last XXXX TBD)