Skip to content

Commit 6accca4

Browse files
amaksimovvamaksimovv
committed
Merge branch 'sfera_plugin' into 'master'
add sfera plugin See merge request CodeScoring/docs!575
2 parents 80b6c53 + a6c99f6 commit 6accca4

5 files changed

Lines changed: 360 additions & 0 deletions

File tree

‎docs/changelog/sfera-changelog.en.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
hide:
3+
- footer
4+
---
5+
6+
# Sfera plugin changelog
7+
8+
### [2025.52.0] - 2025-12-30
9+
10+
#### Added
11+
12+
- Initial release of the Sfera plugin
13+
- Support for the following repository formats:
14+
- Maven
15+
- NPM
16+
- NuGet
17+
- PyPI
18+
- RubyGems
19+
- Go
20+
- APT (Debian)
21+
- YUM (RPM)
22+
- Docker

‎docs/changelog/sfera-changelog.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
hide:
3+
- footer
4+
---
5+
6+
# Changelog плагина для Sfera
7+
8+
### [2025.52.0] - 2025-12-30
9+
10+
#### Добавлено
11+
12+
- Первый релиз плагина для Sfera
13+
- Поддержка следующих форматов репозиториев:
14+
- Maven
15+
- NPM
16+
- NuGet
17+
- PyPI
18+
- RubyGems
19+
- Go
20+
- APT (Debian)
21+
- YUM (RPM)
22+
- Docker

‎docs/osa/sfera_osa.en.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
---
2+
hide:
3+
- footer
4+
---
5+
6+
# Sfera plugin
7+
8+
## Plugin installation
9+
10+
The plugin is delivered as a jar-file.
11+
12+
To install the plugin in **Sfera**, you need to:
13+
14+
1. Place the plugin jar file and config file `codescoring.yaml` into the `plugins` folder located in the application's PPDL working directory.
15+
2. (*Optional*) To manage enabling/disabling of plugins, you can create `enabled.txt` or `disabled.txt` files in the `plugins` folder.
16+
* The file should list the names of the plugins to be enabled or disabled.
17+
* Enable/Disable logic:
18+
* plugin in `disabled.txt` - disabled;
19+
* `enabled.txt` is not empty and does not contain the plugin - disabled;
20+
* in other cases, the plugin is enabled.
21+
22+
## Plugin configuration
23+
24+
The `codescoring.yaml` file is used to configure the plugin.
25+
26+
Example file content:
27+
28+
```yaml
29+
30+
codeScoringAPI:
31+
# The base URL for all CodeScoring API endpoints.
32+
# Required.
33+
# Example: https://host:port or https://host
34+
url:
35+
36+
# Your CodeScoring API Token for authentication.
37+
# Required.
38+
token:
39+
40+
# Http client connection pool size to CodeScoring BE service.
41+
connectionPoolSize: 50
42+
43+
# By default, if CodeScoring API hasn't responded within a duration of 60 seconds, the request will be cancelled.
44+
# This property lets you customize the timeout duration in seconds.
45+
timeout: 60
46+
47+
# If you are using a proxy, you must provide both Hostname/IP and port.
48+
proxy:
49+
host:
50+
port:
51+
52+
# If set to 'false' allows artifact downloads regardless of errors from CodeScoringAPI or plugin
53+
blockOnErrors: true
54+
55+
# If set to 'true', the plugin will scan all supported repositories
56+
# except specified in the "excludeRepositories" section.
57+
scanAllRepositories: false
58+
59+
# Default settings for all repositories. Can be overridden by repositories.repo-name settings
60+
defaults:
61+
dockerRegistryUrl: registry.my.domain
62+
63+
# warmup | Scan cache warmup without requests monitoring, no blocking
64+
# spectator | Scan cache warmup with requests monitoring, no blocking
65+
# moderate | Policy-based blocking using cache results, not scanned component downloads allowed
66+
# strict | Policy-based blocking using cache results, not scanned component downloads blocked
67+
# strict_wait | Policy-based blocking, wait until component is scanned
68+
# default value is strict_wait if not specified in default or repository settings or in case of a typo
69+
workMode: strict_wait
70+
71+
# Allows this user to skip scan
72+
skipScanUser: codescoring
73+
74+
# Repository Manager url for CodeScoring to apply policies.
75+
# Value MUST BE equal to Repository Manager URL in CodeScoring
76+
# Example: https://sfera.my.domain.ru
77+
repositoryManagerUrl:
78+
79+
# Settings per repository
80+
# Example:
81+
# repositories:
82+
# docker-remote:
83+
# docker-local:
84+
# dockerRegistryUrl: another-registry.my.domain
85+
# skipScanUser: anotheruser
86+
# workMode: spectator
87+
# pypi-remote:
88+
# workMode: warmup
89+
repositories:
90+
91+
# List of the excluded repositories. Used, if scanAllRepositories=true
92+
# Example:
93+
# excludeRepositories:
94+
# - npm-remote
95+
# - maven-local
96+
excludeRepositories:
97+
98+
# List of repository types to scan. Used, if scanAllRepositories=true
99+
# Supported values are: maven, npm, pypi, nuget, go, gems, debian, yum, alpine, docker
100+
# Example:
101+
# repositoryTypes:
102+
# - npm
103+
# - go
104+
repositoryTypes:
105+
```
106+
107+
### Parameter Description
108+
109+
- **codeScoringAPI** - configuration parameters for plugin interaction with the CodeScoring platform;
110+
- **url** – CodeScoring platform address (protocol must be specified);
111+
- **token** – API key for authorization (*Created in CodeScoring section `Profile -> Home`*);
112+
- **connectionPoolSize** – connection pool size for CodeScoring platform;
113+
- **timeout** - response timeout (in seconds). By default, if CodeScoring API does not respond within 60 seconds, the request will be cancelled;
114+
- **proxy** - proxy server settings;
115+
- **host** - host/IP;
116+
- **port** - port;
117+
- **blockOnErrors** - block component downloads in case of an error during interaction with the CodeScoring platform;
118+
- **scanAllRepositories** - enable scanning for all supported repositories except those specified in the **excludeRepositories** parameter;
119+
- **defaults** – default scanning settings for all connected repositories;
120+
- **dockerRegistryUrl** – docker registry address;
121+
- **workMode** – plugin operation mode. Conditions for each mode are described in the section below;
122+
- **skipScanUser** – user for whom component scanning is skipped. Necessary so that CodeScoring can independently retrieve the component for scanning;
123+
- **repositoryManagerUrl** - Sfera URL. The same URL must be specified in CodeScoring to apply policies by repositories.
124+
- **repositories** – list of repositories for which component scanning is active. Parameters can be specified separately for each repository, same as in **defaults**;
125+
- **excludeRepositories** - list of repository names excluded from processing by the plugin.
126+
127+
### Work Mode Configuration
128+
129+
The plugin's operation mode is determined by the **workMode** variable in the `codescoring.yaml` file.
130+
131+
The plugin has 6 modes of operation that determine the strictness of component verification before download.
132+
133+
- **warmup** – load data into CodeScoring cache without blocking components;
134+
- **spectator** – load data into CodeScoring cache without blocking components, save component request results on the platform;
135+
- **moderate** – block components that fail policy checks. Downloading unscanned components is allowed;
136+
- **strict** – block components that fail policy checks. Downloading unscanned components is forbidden;
137+
- **strict_wait** – block components that fail policy checks. Wait for verification for unscanned components.
138+
139+
**Important**: the selected operation mode will affect **all** repositories specified in the `repositories` variable.
140+
141+
## Component Blocking
142+
143+
When a component download is blocked, one of the following blocking reasons is displayed in the user console:
144+
145+
- **"The download has been blocked in accordance with the policies configured in CodeScoring"** – component blocked according to policies configured on the platform;
146+
- **"The component has not yet been scanned by CodeScoring, it is scheduled to be scanned shortly. The download is blocked according to the plugin settings"** – blocked unscanned component with subsequent scan initiation. Used in `strict` mode;
147+
- **"The download has been blocked due to the failure of the scan of the component in CodeScoring"** – failed to scan the component;
148+
- **"The download has been blocked due to the wrong mode of the plugin"** – incorrect [plugin operation mode](#work-mode-configuration) is used;
149+
- **"The download has been blocked due to the timeout of the scan of the component in CodeScoring"** – component scan timeout expired. Used in `strict_wait` mode;
150+
- **"The download has been blocked, because registry is not configured in CodeScoring"** – corresponding Registry is missing in the platform.
151+
152+
The response also contains a link to the component page in CodeScoring with information about triggered security policies and found vulnerabilities:
153+
154+
![Component page](/assets/img/osa/component-page.png)

‎docs/osa/sfera_osa.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
---
2+
hide:
3+
- footer
4+
---
5+
6+
# Плагин для Sfera
7+
8+
## Установка плагина
9+
10+
Плагин поставляется в виде jar-файла.
11+
12+
Для установки плагина в **Sfera** необходимо:
13+
14+
1. Поместить jar-файл плагина и файл конфигурации `codescoring.yaml` в папку `plugins`, находящуюся в рабочей директории PPDL приложения.
15+
2. (*Опционально*) Для управления включением/отключением плагинов можно создать в папке `plugins` файлы `enabled.txt` или `disabled.txt`.
16+
* В файле должны быть перечислены имена включаемых/отключаемых плагинов.
17+
* Логика включения/выключения:
18+
* плагин в `disabled.txt` - отключен;
19+
* `enabled.txt` не пуст и при этом не содержит плагин - отключен;
20+
* в остальных случаях плагин включен.
21+
22+
## Настройка плагина
23+
24+
Для настройки плагина используется файл `codescoring.yaml`.
25+
26+
Пример содержания файла:
27+
28+
```yaml
29+
30+
codeScoringAPI:
31+
# Базовый URL для всех эндпоинтов CodeScoring API.
32+
# Обязательный параметр.
33+
# Пример: https://host:port или https://host
34+
url:
35+
36+
# Ваш API токен CodeScoring для аутентификации.
37+
# Обязательный параметр.
38+
token:
39+
40+
# Размер пула соединений HTTP-клиента к сервису CodeScoring BE.
41+
connectionPoolSize: 50
42+
43+
# По умолчанию, если CodeScoring API не ответил в течение 60 секунд, запрос будет отменен.
44+
# Этот параметр позволяет настроить длительность таймаута в секундах.
45+
timeout: 60
46+
47+
# Если вы используете прокси, необходимо указать Hostname/IP и порт.
48+
proxy:
49+
host:
50+
port:
51+
52+
# Если установлено значение 'false', разрешает загрузку артефактов независимо от ошибок CodeScoringAPI или плагина
53+
blockOnErrors: true
54+
55+
# Если установлено значение 'true', плагин будет сканировать все поддерживаемые репозитории,
56+
# за исключением указанных в разделе "excludeRepositories".
57+
scanAllRepositories: false
58+
59+
# Настройки по умолчанию для всех репозиториев. Могут быть переопределены в настройках конкретных репозиториев (repositories.repo-name)
60+
defaults:
61+
dockerRegistryUrl: registry.my.domain
62+
63+
# warmup | Прогрев кэша сканирования без мониторинга запросов, без блокировки
64+
# spectator | Прогрев кэша сканирования с мониторингом запросов, без блокировки
65+
# moderate | Блокировка на основе политик с использованием результатов кэша, разрешена загрузка непросканированных компонентов
66+
# strict | Блокировка на основе политик с использованием результатов кэша, загрузка непросканированных компонентов заблокирована
67+
# strict_wait | Блокировка на основе политик, ожидание завершения сканирования компонента
68+
# значение по умолчанию — strict_wait, если оно не указано в настройках или в случае опечатки
69+
workMode: strict_wait
70+
71+
# Позволяет этому пользователю пропускать сканирование
72+
skipScanUser: codescoring
73+
74+
# URL менеджера репозиториев для применения политик CodeScoring.
75+
# Значение ДОЛЖНО быть равно Repository Manager URL в CodeScoring
76+
# Пример: https://sfera.my.domain.ru
77+
repositoryManagerUrl:
78+
79+
# Настройки для конкретных репозиториев
80+
# Пример:
81+
# repositories:
82+
# docker-remote:
83+
# docker-local:
84+
# dockerRegistryUrl: another-registry.my.domain
85+
# skipScanUser: anotheruser
86+
# workMode: spectator
87+
# pypi-remote:
88+
# workMode: warmup
89+
repositories:
90+
91+
# Список исключенных репозиториев. Используется, если scanAllRepositories=true
92+
# Пример:
93+
# excludeRepositories:
94+
# - npm-remote
95+
# - maven-local
96+
excludeRepositories:
97+
98+
# Список типов репозиториев для сканирования. Используется, если scanAllRepositories=true
99+
# Поддерживаемые значения: maven, npm, pypi, nuget, go, gems, debian, yum, alpine, docker
100+
# Пример:
101+
# repositoryTypes:
102+
# - npm
103+
# - go
104+
repositoryTypes:
105+
```
106+
107+
### Описание параметров
108+
109+
- **codeScoringAPI** - настройки параметров взаимодействия плагина с платформой CodeScoring;
110+
- **url** – адрес платформы CodeScoring (обязательно указание протокола);
111+
- **token** – ключ для авторизации вызовов API (*Создается из CodeScoring раздела `Profile -> Home`*);
112+
- **connectionPoolSize** – размер пула соединений с платформой CodeScoring;
113+
- **timeout** - время ожидания ответа (в секундах). По умолчанию, если CodeScoring API не отвечает в течение 60 секунд, запрос будет отменен;
114+
- **proxy** - настройки прокси-сервера;
115+
- **host** - хост/IP;
116+
- **port** - порт;
117+
- **blockOnErrors** - блокирование загрузки компонентов в случае ошибки при взаимодействии с платформой CodeScoring;
118+
- **scanAllRepositories** - подключение всех поддерживаемых репозиториев за исключением указанных в параметре **excludeRepositories**;
119+
- **defaults** – настройки сканирования по умолчанию для всех подключенных репозиториев;
120+
- **dockerRegistryUrl** – адрес docker registry;
121+
- **workMode** – режим работы плагина. Условия каждого режима работы описаны в секции ниже;
122+
- **skipScanUser** – пользователь, для которого пропускается сканирование компонентов. Необходимо для того, чтобы CodeScoring мог самостоятельно забрать компонент для сканирования;
123+
- **repositoryManagerUrl** - URL Sfera. Тот же URL должен быть указан в CodeScoring для применения политик по репозиториям.
124+
- **repositories** – список репозиториев, для которых работает сканирование компонентов. Для каждого репозитория можно отдельно указать параметры, как в параметре **defaults**;
125+
- **excludeRepositories** - список названий репозиториев, исключенных из обработки плагином.
126+
127+
### Настройка режимов работы {: #work-mode-configuration }
128+
129+
Режим работы плагина определяется переменной **workMode** в файле `codescoring.yaml`.
130+
131+
Плагин имеет 6 режимов работы, определяющих строгость проверки компонентов перед загрузкой.
132+
133+
- **warmup** – загрузка данных в кэш CodeScoring без блокировки компонентов;
134+
- **spectator** – загрузка данных в кэш CodeScoring без блокировки компонентов, сохранение результатов запросов компонентов на платформе;
135+
- **moderate** – блокировка компонентов, не прошедших проверку политик. Разрешена загрузка непросканированных компонентов;
136+
- **strict** – блокировка компонентов, не прошедших проверку политик. Запрещена загрузка непросканированных компонентов;
137+
- **strict_wait** – блокировка компонентов, не прошедших проверку политик. Ожидание проверки для непросканированных компонентов.
138+
139+
**Важно**: выбранный режим работы будет влиять на **все** репозитории, указанные в переменной `repositories`.
140+
141+
## Блокировка компонента
142+
143+
При блокировании загрузки компонента в консоли пользователя отображается одна из следующих причин блокировки:
144+
145+
- **"The download has been blocked in accordance with the policies configured in CodeScoring"** – блокировка компонента согласно настроенным на платформе политикам;
146+
- **"The component has not yet been scanned by CodeScoring, it is scheduled to be scanned shortly. The download is blocked according to the plugin settings"** – блокировка непросканированного компонента с последующим запуском сканирования. Используется в режиме `strict`;
147+
- **"The download has been blocked due to the failure of the scan of the component in CodeScoring"** – не удалось просканировать компонент;
148+
- **"The download has been blocked due to the wrong mode of the plugin"** – используется некорректный [режим работы плагина](#work-mode-configuration);
149+
- **"The download has been blocked due to the timeout of the scan of the component in CodeScoring"** – истекло время ожидания сканирования компонента. Используется в режиме `strict_wait`;
150+
- **"The download has been blocked, because registry is not configured in CodeScoring"** – отсутствует соответствующий Registry в платформе.
151+
152+
Ответ также содержит ссылку на страницу компонента в CodeScoring с информацией о сработавших политиках безопасности и найденных уязвимостях:
153+
154+
![Component page](/assets/img/osa/component-page.png)

0 commit comments

Comments
 (0)