si-engine
1.3.24
dotnet tool install --global si-engine --version 1.3.24
dotnet new tool-manifest
dotnet tool install --local si-engine --version 1.3.24
#tool dotnet:?package=si-engine&version=1.3.24
nuke :add-package si-engine --version 1.3.24
si-engine
Software Intelligence and static analysis tool for ASP.NET Core and SQL Server — English · Italiano · https://sie.lupala.com
English
SIE reads an ASP.NET / C# application (and, optionally, its SQL Server database in read-only mode) and builds verifiable knowledge about it: pages, controllers, services, data access, tables, business rules, dependencies. Every element carries evidence (file and line) and a confidence; whatever is inferred is labelled as such. The result can be queried from the command line, from a local API and from an MCP server for AI agents, and exported as documentation for people and as knowledge for LLMs.
This README is the complete guide of the package (installation, usage, every feature) and is updated with every release.
What it analyses
| Area | What it extracts |
|---|---|
| C# / .NET | Projects, dependencies, types, DI registrations, call graph (also library-only and console solutions) |
| ASP.NET Core | Controllers, actions, Razor Pages, minimal APIs, Blazor, views, routes, permissions |
| ASP.NET MVC 5 | Controllers, actions and Razor views (basic analysis, conventional route) |
| ASP.NET Web Forms | .aspx, .ascx, .master, code-behind, server controls, events, data sources, bindings, menus |
| Web Site without project | Pages discovered from files (web.config, .aspx/.ascx/.master) |
| Data access | EF Core, Dapper, ADO.NET, SqlDataSource/ObjectDataSource: which pages read or write which tables |
| SQL Server (optional) | Tables, columns, keys, indexes, views, procedures, functions, triggers, dependencies (never the data) |
| Business rules | Guard clauses, validators, database constraints |
Analysis modules switch themselves on according to what they find in the repository (si-engine modules list). The analysed code is never compiled or executed.
1. Installation
Prerequisite: .NET 10 SDK, or the .NET 10 runtime with ASP.NET Core (Microsoft.AspNetCore.App): the tool is framework-dependent. Optional: a SQL Server reachable with a read-only account.
From NuGet:
dotnet tool install -g si-engine
dotnet tool update -g si-engine
dotnet tool uninstall -g si-engine
From a folder with si-engine.<version>.nupkg files (no feed needed):
dotnet tool update -g si-engine --add-source /path/to/folder --version 1.3.24
export PATH="$PATH:$HOME/.dotnet/tools" # if `si-engine` is not found
si-engine --version
dotnet tool update installs the tool if missing and updates it otherwise. If nothing changes: dotnet tool uninstall -g si-engine, then dotnet tool install -g si-engine --add-source /path/to/folder --version 1.3.24. File check: sha256sum -c SHA256SUMS --ignore-missing.
2. First steps
si-engine init # creates the workspace in the current directory
si-engine app add --name "My App" --repository /path/to/repo # registers the application (id: my-app)
si-engine scan --application my-app # scan
si-engine status --application my-app # outcome and coverage
si-engine export human --application my-app # documentation in <workspace>/output/my-app/human
- Workspace:
--workspace <dir>, otherwiseSIE_HOME, otherwise the current directory. It holds the SQLite database, applications, logs and output. One workspace serves all applications. - Every scan is immutable (
my-app-scan-001,-002, ...): the other features work on the active scan or on the one given with--scan. - Supported repositories: with
.sln/.slnx/.csproj(SDK-style or legacy), or a Web Site without a project (at least one.aspx/.ascx/.masterfile, also next to.csprojprojects when outside their folders). Otherwise the error isinvalid_repository(exit 4).
With the database (optional)
The connection string lives only in an SIE_* environment variable, never in configuration or on the command line:
export SIE_MY_DB='Server=...;Database=...;User Id=...;Password=...'
si-engine app add --name "My App" --repository /path/to/repo --database-ref env:SIE_MY_DB
si-engine database test --application my-app # connection and permissions (VIEW DEFINITION, read-only)
If the database is unreachable scan does not fail: it continues on the source only, raises database.extraction_failed and declares it in the coverage (exit 0).
3. All commands
Global options, valid for every command: --json (a single JSON document on stdout), -q/--quiet, -v/--verbosity trace|debug|information|warning|error, -w/--workspace <dir>, -h/--help, --version.
| Command | What it does | Main options |
|---|---|---|
init |
Creates the workspace (folders, appsettings.json, SQLite). Idempotent |
— |
app add |
Registers an application | --name, --repository, --database-ref env:SIE_X, --description, --exclude <path> (repeatable; */? allowed, a single segment matches at any depth, e.g. ENCRYPTER, PROJECTS/*.Job) |
app update |
Changes a registered application (options left out keep their value) | --application*, --repository, --database-ref env:SIE_X, --no-database, --description, --exclude <path> (repeatable, replaces the list) |
app list |
Lists the registered applications | — |
database test |
Tests the connection and permissions (exit 3 on failure) | -a* |
scan |
Scans and stores an immutable scan | -a*, --source-only, --database-only, --incremental |
scanHL |
Like scan + detailed report (timings, projects, warnings, Web Forms pages, skipped files, database, gaps) + human and llm export of the scan in <workspace>/output |
as scan, plus -o, --no-export |
status |
State of the application and of its last scan (metrics, modules, coverage) | -a* |
modules list |
Analysis modules: version, phase, dependencies, applicability, configured state; with -a the outcome in the last scan |
-a, --scan |
export human |
Documentation for people: Markdown, Mermaid, CSV | -a*, -o, --format markdown,mermaid,csv, --scan |
export llm |
Knowledge for LLMs: JSON and compact chunks | -a*, -o, --format json,compact,knowledge, --scan, --no-evidence |
search |
Full-text search in the model (SQLite FTS5) | -a, --query, --type, --limit, --module, --file, --related-to, --relationship, --mode fulltext\|name, --scan |
context |
Token-budgeted context pack for a table, page, class, service, rule, module or free text | -a, --query, --max-tokens (12000), --max-characters, --include-evidence, --max-depth, --scan |
impact |
What a change to an element may affect | -a, --target (e.g. table:dbo.orders), --max-depth (5), -o, --scan |
diff |
Compares two scans (added, removed, changed) | -a, --from, --to* |
api serve |
Read-only local API on 127.0.0.1 (token in <workspace>/api-token) |
--port (5127) |
mcp serve |
Read-only MCP server over stdio, for AI agents | — |
* required. -a = --application (id or name). Full reference: si-engine <command> --help.
Examples
si-engine scanHL -a my-app --source-only # understand why a scan is incomplete
si-engine scan -a my-app --incremental # reuse whatever did not change
si-engine search -a my-app --query "customer orders" --type page
si-engine context -a my-app --query "table:dbo.orders" --max-tokens 8000 --include-evidence
si-engine impact -a my-app --target table:dbo.orders -o ./report
si-engine diff -a my-app --from 1 --to 2
si-engine export llm -a my-app --format json,compact,knowledge
si-engine modules list -a my-app
4. Output
export human(<workspace>/output/<app>/human): Markdown documents in Italian (overview, modules, pages, database, rules, API, security, coverage), Mermaid diagrams (architecture, dependencies, ER), CSV (entities, relationships, rules, tables, columns),scan-report.md.export llm(.../llm):manifest.json,index.json, one JSON per entity, relationships by type, evidence, context packs per module and table, chunks in compact format with token estimates; with--format knowledgealsoknowledge.json(canonical snapshot).- Deterministic output: same code, same files. Secrets are redacted before persistence and output.
5. AI agent integration
MCP — si-engine --workspace <dir> mcp serve (absolute paths in the client configuration: Claude Desktop, Claude Code, VS Code, OpenCode). Ten read-only tools: sie_list_applications, sie_get_overview, sie_search, sie_get_page, sie_get_table, sie_get_business_rule, sie_get_dependencies, sie_get_relationships, sie_generate_context, sie_analyze_impact.
Local API — si-engine api serve: loopback only, Bearer token, rate limiting. Prefix /api/v1: list/register applications, asynchronous scans (POST /applications/{id}/scans) and cancellation, knowledge, paginated entities and relationships, search, context, impact, ZIP exports.
6. Settings to define before starting the program
Environment variables (they override <workspace>/appsettings.json; use __ instead of :). The full list is in si-engine --help.
| Variable | Effect |
|---|---|
SIE_HOME |
Workspace directory |
SIE_<NAME> |
Connection string referenced by --database-ref env:SIE_<NAME> |
NUGET_PACKAGES |
NuGet cache used to resolve references |
Storage__Path |
SQLite database path (default ./data/sie.db); keep it on a local disk, not USB or network |
Storage__BusyTimeoutSeconds |
How long to wait for the database lock held by another session (1-3600, default 30) |
Storage__SharedAccess |
true: the owner's group can read and write the workspace (0660/0770 + setgid), several users on one workspace |
Analysis__MaxParallelism |
Analyzers running at once (1-256, default 4) |
Analysis__MaxFileSizeMb |
Larger files are skipped and declared (1-1024, default 20) |
Analysis__AnalyzeLegacyProjects |
true: analyse the C# of every legacy project (Web Forms and MVC 5 always are) |
Analysis__PreprocessorSymbols__<n> |
Extra #if symbol set, e.g. "DEBUG;TRACE" |
Analysis__Modules__<id>__Enabled |
Auto (default), On (force), Off (disable) for one module |
Database__CommandTimeoutSeconds, Database__ReadOnlyRequired |
Timeout (default 60) and refusal of accounts with write permissions (default true) |
Export__Human, Export__Llm, Export__Mermaid, Export__Csv |
false disables an export (exit 6) |
Search__Glossary__* |
Italian/English search glossary |
Api__Port, Api__AllowedRepositoryRoots__<n>, Api__RequestsPerMinute |
Local API settings |
Logging__LogLevel__Default |
Log level (the log file records at least Information) |
Module ids: csharp, aspnet-core, aspnet-mvc5, aspnet-webforms, aspnet-navigation, data-access, business-rules. Example:
env "Analysis__Modules__aspnet-webforms__Enabled=On" Analysis__MaxParallelism=2 si-engine scan --application my-app
A name with a hyphen is not valid for export in sh: use env.
7. Incremental scan, coverage and confidence
--incrementalreuses the results of the modules whose input did not change; the result is identical to a full scan. When it cannot, it runs a full scan and says why.- Every scan declares its coverage: what was analysed, what was not and why (gaps). Status
completed_with_warnings= valid scan with declared gaps. - Every entity has a confidence and an inferred flag; evidence gives file, lines and method.
8. Security and limits
- The analysed repository is untrusted input: no code executed, no MSBuild, confined paths, external symlinks ignored. Secret files (
.env,*.pfx,*.pem,appsettings*.json) are never read. - Database: metadata only, never data;
ApplicationIntent=ReadOnly; connection strings are never stored or printed. API on loopback only. - Limits: Web Forms and MVC 5 without MSBuild leave
System.Webreferences unresolved (partial «source» coverage); SQL Server only; code generated at build time is not seen;#ifcombinations are not exhaustive.
9. Exit codes
0 ok · 1 general error · 2 invalid configuration · 3 database unreachable · 4 invalid repository · 5 incomplete scan · 6 export failed · 130 cancelled (Ctrl+C).
10. Troubleshooting
si-engine: command not found: add$HOME/.dotnet/toolstoPATH.- Runtime error at startup: install the ASP.NET Core Runtime 10.
workspace_not_initialized: runsi-engine init(or use--workspace/SIE_HOME).invalid_repository: the path does not exist or contains no solutions, projects or Web Forms files.- Web Forms pages without events or data: look at
si-engine scanHLand thewebforms.code_behind_not_foundwarning. - Logs in
<workspace>/logs/; more detail with-v debug(steps and durations) and-v trace(also one message per project and technology). For a long run:si-engine scan -a <app> -v debug 2>&1 | tee scan.log.
License: MIT.
Related tools
- AzDo — Azure DevOps CLI and MCP server
- JiraCli-Mcp — Jira CLI and MCP server
- SharpGuard — .NET SAST/SCA security scanner
Version 1.3.24
What is new compared with 1.3.0:
Security and export status: T-SQL parser messages and the scan report are masked before they are printed or emitted; with both exports disabled
scanHLreportsdisabled(no files, exit code unchanged).Multi-root design note (no behaviour change):
docs/adr/ADR-0009-repository-multi-root.mdexplains why declaring several roots in one application was not done in this series and how to do it in steps (prefixed paths, a guard per root, per-root fingerprints).Memory in huge scans: the stage artifact is written already gzip-compressed and verified by streaming, so the JSON document (hundreds of MB) is never held in memory; with
-v debugthe C# analysis logs the managed and resident memory at every phase (Roslyn memory after ...).Legacy T-SQL: SQL modules (stored procedures, views, functions, triggers) are parsed with the QUOTED_IDENTIFIER setting they were created with (
sys.sql_modules.uses_quoted_identifier) and the database compatibility level; if that is not enough the opposite setting and then older parsers are tried, and every attempt is in thedataaccess.module_parse_errorwarning (or in the informationaldataaccess.module_parse_fallbackwarning when it succeeds after a fallback).Path safety: the cache of the symbolic-link checks (valid only inside one discovery/analysis pass) is now safe with several threads (
Task.Run,Parallel) and nested scopes; the file and its immediate folder are checked on every read.Page → stored procedure precision: a call attributed to its only candidate (argument types unresolved) has its own rule at 0.6 and a path through it is «possible» in the impact analysis (with every edge resolved it stays «transitive»); a stored procedure name passed as a constant to a helper that executes it (one level) gives the access to the caller.
Mixed repositories (
.csproj+ Web Site without a project file): the Web Site outside the project folders is synthesised as a separate project (name made unique with the.WebSitesuffix if it equals a project name), and the page → data-layer class → stored procedure/table link works also without a connected database.scanHL also writes the files: after the scan it runs the same exports as
export humanandexport llminto<workspace>/output/<application>/{human,llm}(-oto change the folder,--no-exportto skip them); if the export fails the scan stays saved and the exit code is 6.Very large scans: the stage artifact of call graphs with hundreds of thousands of edges stays UTF-8 until it is stored and the heap is compacted after heavy modules: a scan with ~685,000 calls no longer runs out of memory.
Skipped legacy projects = «source» coverage gap: without
Analysis__AnalyzeLegacyProjects=truethe C# of non SDK-style projects is skipped and the report says so and how to enable it;--excludeaccepts wildcards and is applied before any file is read;code.missing_referenceslists the most frequent unresolved names; upper-case*_SERVICEclasses are recognised.The package ships a single documentation file: this README, in Italian and English.
si-engine --helplists every command with its options, the environment variables and configuration keys to set before starting the program, the module ids and the exit codes.New command
app updateto change an already registered application (repository, database, description, exclusions) without editing files by hand;lastScanIdin the application summary (MCP and API); a failed scan leaves no partial rows; a Web Site at the repository root has a fixed name (WebSite).Stored procedures called through helpers: with a database connected, a string or constant equal to a stored procedure name links the method to the procedure (confidence 0.5), so pages and classes reach the tables even when the ADO.NET call goes through a helper or a data access block (AB#47).
Pages not linked to the database:
scanHLprints «Pagine → database: N of M linked» with the reason for the others; the same data (pageLinkage) is insie_get_overview(MCP) and in the API.«database is locked»: the search index is built in batches under a cross-process lock (one session builds it, the others wait), starting a command no longer asks for the write lock, and the error is now
database_lockedwith a hint on what to do.More sessions and users: storing a scan no longer locks the database for minutes (short transactions, a failed scan leaves nothing behind);
Storage__BusyTimeoutSecondssets how long to wait for the lock (default 30 s) andStorage__SharedAccess=truelets a group of users share one workspace.More detail with
-v debugand-v trace: duration of every discovery step, applicability decision and duration of every module, per-project Roslyn timings, timing of every SQL Server catalog query and of every phase of the scan write (to see where the time goes).A Web Site solution (
.slnlisting the site folder, no.csproj) is now recognised; stored procedures created withQUOTED_IDENTIFIER OFF(double-quoted strings) no longer give parse errors.ASP.NET Web Sites without
.sln/.csprojcan be scanned (onlyweb.config+.aspx/.ascx/.master): pages are discovered from the files and the warningdiscovery.website_without_projectis raised. A project is synthesised from the site folder and its C# (App_Code, code-behind) is analysed like a Web Forms project.
Italiano
SIE legge un'applicazione ASP.NET / C# (e, se vuoi, il suo database SQL Server in sola lettura) e costruisce una conoscenza verificabile dell'applicazione: pagine, controller, servizi, accessi ai dati, tabelle, regole di business, dipendenze. Ogni elemento porta l'evidenza (file e riga) e una confidence; ciò che è dedotto è dichiarato come tale. Il risultato è interrogabile da riga di comando, da un'API locale e da un server MCP per agenti AI, ed è esportabile come documentazione per persone e come knowledge per LLM.
Questo README è la guida completa del pacchetto (installazione, uso, tutte le funzioni) e viene aggiornato a ogni versione.
Cosa analizza
| Area | Cosa ricava |
|---|---|
| C# / .NET | Progetti, dipendenze, tipi, registrazioni DI, call graph (anche solution di sole librerie o console) |
| ASP.NET Core | Controller, azioni, Razor Pages, minimal API, Blazor, viste, rotte, permessi |
| ASP.NET MVC 5 | Controller, azioni e viste Razor (analisi di base, rotta convenzionale) |
| ASP.NET Web Forms | .aspx, .ascx, .master, code-behind, controlli server, eventi, data source, binding, menu |
| Web Site senza progetto | Pagine trovate dai file (web.config, .aspx/.ascx/.master) |
| Accessi ai dati | EF Core, Dapper, ADO.NET, SqlDataSource/ObjectDataSource: quali pagine leggono o scrivono quali tabelle |
| SQL Server (facoltativo) | Tabelle, colonne, chiavi, indici, viste, procedure, funzioni, trigger, dipendenze (mai i dati) |
| Regole di business | Guard clause, validatori, vincoli del database |
I moduli di analisi si attivano da soli in base a ciò che trovano nel repository (si-engine modules list). Il codice analizzato non viene mai compilato né eseguito.
1. Installazione
Prerequisito: .NET 10 SDK, oppure il runtime .NET 10 con ASP.NET Core (Microsoft.AspNetCore.App): il tool è framework-dependent. Facoltativo: SQL Server raggiungibile con un account di sola lettura.
Da NuGet:
dotnet tool install -g si-engine
dotnet tool update -g si-engine
dotnet tool uninstall -g si-engine
Da una cartella con i file si-engine.<versione>.nupkg (nessun feed necessario):
dotnet tool update -g si-engine --add-source /percorso/cartella --version 1.3.24
export PATH="$PATH:$HOME/.dotnet/tools" # se `si-engine` non viene trovato
si-engine --version
dotnet tool update installa il tool se manca e lo aggiorna se c'è già. Se non cambia nulla: dotnet tool uninstall -g si-engine e poi dotnet tool install -g si-engine --add-source /percorso/cartella --version 1.3.24. Verifica del file: sha256sum -c SHA256SUMS --ignore-missing.
2. Primo utilizzo
si-engine init # crea il workspace nella directory corrente
si-engine app add --name "Mia App" --repository /percorso/repo # registra l'applicazione (id: mia-app)
si-engine scan --application mia-app # scansione
si-engine status --application mia-app # esito e copertura
si-engine export human --application mia-app # documentazione in <workspace>/output/mia-app/human
- Workspace:
--workspace <dir>, altrimentiSIE_HOME, altrimenti la directory corrente. Contiene database SQLite, applicazioni, log, output. Un workspace per tutte le applicazioni. - Ogni scansione è immutabile (
mia-app-scan-001,-002, ...): le altre funzioni lavorano sulla scansione attiva o su quella indicata con--scan. - Repository supportati: con
.sln/.slnx/.csproj(SDK-style o legacy), oppure Web Site senza progetto (almeno un file.aspx/.ascx/.master, anche accanto a progetti.csprojse fuori dalle loro cartelle). Altrimenti erroreinvalid_repository(exit 4).
Con il database (facoltativo)
La stringa di connessione sta solo in una variabile d'ambiente SIE_*, mai nella configurazione né nella riga di comando:
export SIE_MIO_DB='Server=...;Database=...;User Id=...;Password=...'
si-engine app add --name "Mia App" --repository /percorso/repo --database-ref env:SIE_MIO_DB
si-engine database test --application mia-app # connessione e permessi (VIEW DEFINITION, sola lettura)
Se il database non è raggiungibile scan non fallisce: prosegue solo sul sorgente, emette database.extraction_failed e lo dichiara nella copertura (exit 0).
3. Tutti i comandi
Opzioni globali, valide per ogni comando: --json (un solo documento JSON su stdout), -q/--quiet, -v/--verbosity trace|debug|information|warning|error, -w/--workspace <dir>, -h/--help, --version.
| Comando | Cosa fa | Opzioni principali |
|---|---|---|
init |
Crea il workspace (cartelle, appsettings.json, SQLite). Idempotente |
— |
app add |
Registra un'applicazione | --name, --repository, --database-ref env:SIE_X, --description, --exclude <percorso> (ripetibile; */? ammessi, un solo segmento vale a qualsiasi profondità, es. ENCRYPTER, PROJECTS/*.Job) |
app update |
Modifica un'applicazione registrata (le opzioni non passate restano invariate) | --application*, --repository, --database-ref env:SIE_X, --no-database, --description, --exclude <percorso> (ripetibile, sostituisce l'elenco) |
app list |
Elenca le applicazioni registrate | — |
database test |
Prova la connessione e i permessi (exit 3 se fallisce) | -a* |
scan |
Scansione, salva una scansione immutabile | -a*, --source-only, --database-only, --incremental |
scanHL |
Come scan + report dettagliato (tempi, progetti, warning, pagine Web Forms, file saltati, database, lacune) + export human e llm della scansione in <workspace>/output |
come scan, più -o, --no-export |
status |
Stato dell'applicazione e dell'ultima scansione (metriche, moduli, copertura) | -a* |
modules list |
Moduli di analisi: versione, fase, dipendenze, applicabilità, stato configurato; con -a l'esito nell'ultima scansione |
-a, --scan |
export human |
Documentazione per persone: Markdown, Mermaid, CSV | -a*, -o, --format markdown,mermaid,csv, --scan |
export llm |
Knowledge per LLM: JSON e chunk compatti | -a*, -o, --format json,compact,knowledge, --scan, --no-evidence |
search |
Ricerca full-text nel modello (SQLite FTS5) | -a, --query, --type, --limit, --module, --file, --related-to, --relationship, --mode fulltext\|name, --scan |
context |
Context pack con budget di token per una tabella, pagina, classe, servizio, regola, modulo o testo libero | -a, --query, --max-tokens (12000), --max-characters, --include-evidence, --max-depth, --scan |
impact |
Cosa può toccare una modifica a un elemento | -a, --target (es. table:dbo.orders), --max-depth (5), -o, --scan |
diff |
Confronta due scansioni (aggiunto, rimosso, modificato) | -a, --from, --to* |
api serve |
API locale di sola lettura su 127.0.0.1 (token in <workspace>/api-token) |
--port (5127) |
mcp serve |
Server MCP di sola lettura su stdio, per agenti AI | — |
* obbligatoria. -a = --application (id o nome). Il riferimento completo è in si-engine <comando> --help.
Esempi
si-engine scanHL -a mia-app --source-only # capire perché una scansione è incompleta
si-engine scan -a mia-app --incremental # riusa ciò che non è cambiato
si-engine search -a mia-app --query "ordini cliente" --type page
si-engine context -a mia-app --query "table:dbo.orders" --max-tokens 8000 --include-evidence
si-engine impact -a mia-app --target table:dbo.orders -o ./report
si-engine diff -a mia-app --from 1 --to 2
si-engine export llm -a mia-app --format json,compact,knowledge
si-engine modules list -a mia-app
4. Output
export human(<workspace>/output/<app>/human): documenti Markdown in italiano (panoramica, moduli, pagine, database, regole, API, sicurezza, copertura), diagrammi Mermaid (architettura, dipendenze, ER), CSV (entità, relazioni, regole, tabelle, colonne),scan-report.md.export llm(.../llm):manifest.json,index.json, un JSON per entità, relazioni per tipo, evidenze, context pack per modulo e tabella, chunk in formato compatto con stima dei token; con--format knowledgeancheknowledge.json(snapshot canonico).- Output deterministico: a parità di codice, stessi file. Segreti redatti prima di persistenza e output.
5. Integrazione con agenti AI
MCP — si-engine --workspace <dir> mcp serve (percorsi assoluti nella configurazione del client: Claude Desktop, Claude Code, VS Code, OpenCode). Dieci tool di sola lettura: sie_list_applications, sie_get_overview, sie_search, sie_get_page, sie_get_table, sie_get_business_rule, sie_get_dependencies, sie_get_relationships, sie_generate_context, sie_analyze_impact.
API locale — si-engine api serve: solo loopback, token Bearer, rate limit. Prefisso /api/v1: elenco/registrazione applicazioni, avvio asincrono di scansioni (POST /applications/{id}/scans) e annullamento, conoscenza, entità e relazioni paginate, search, context, impact, export ZIP.
6. Impostazioni da definire prima di avviare il programma
Variabili d'ambiente (battono <workspace>/appsettings.json; __ al posto di :). L'elenco completo è in si-engine --help.
| Variabile | Effetto |
|---|---|
SIE_HOME |
Directory del workspace |
SIE_<NOME> |
Stringa di connessione referenziata da --database-ref env:SIE_<NOME> |
NUGET_PACKAGES |
Cache NuGet usata per risolvere i riferimenti |
Storage__Path |
Percorso del database SQLite (default ./data/sie.db); tienilo su un disco locale, non su USB o di rete |
Storage__BusyTimeoutSeconds |
Attesa del lock del database tenuto da un'altra sessione (1-3600, default 30) |
Storage__SharedAccess |
true: il gruppo del proprietario legge e scrive il workspace (0660/0770 + setgid), più utenti sullo stesso workspace |
Analysis__MaxParallelism |
Analizzatori in parallelo (1-256, default 4) |
Analysis__MaxFileSizeMb |
File più grandi saltati e dichiarati (1-1024, default 20) |
Analysis__AnalyzeLegacyProjects |
true: analizza il C# di tutti i progetti legacy (Web Forms e MVC 5 lo sono sempre) |
Analysis__PreprocessorSymbols__<n> |
Insieme extra di simboli #if, es. "DEBUG;TRACE" |
Analysis__Modules__<id>__Enabled |
Auto (default), On (forza), Off (spegne) per un modulo |
Database__CommandTimeoutSeconds, Database__ReadOnlyRequired |
Timeout (default 60) e rifiuto di account con permessi di scrittura (default true) |
Export__Human, Export__Llm, Export__Mermaid, Export__Csv |
false disabilita un export (exit 6) |
Search__Glossary__* |
Glossario italiano/inglese della ricerca |
Api__Port, Api__AllowedRepositoryRoots__<n>, Api__RequestsPerMinute |
Impostazioni dell'API locale |
Logging__LogLevel__Default |
Livello di log (il file registra almeno Information) |
Id dei moduli: csharp, aspnet-core, aspnet-mvc5, aspnet-webforms, aspnet-navigation, data-access, business-rules. Esempio:
env "Analysis__Modules__aspnet-webforms__Enabled=On" Analysis__MaxParallelism=2 si-engine scan --application mia-app
Il nome con il trattino non è valido per export in sh: usa env.
7. Scansione incrementale, copertura e confidence
--incrementalriusa i risultati dei moduli il cui input non è cambiato; il risultato è identico a una scansione completa. Se non può, esegue una scansione completa e dice perché.- Ogni scansione dichiara la copertura: cosa è stato analizzato, cosa no e perché (lacune). Esito
completed_with_warnings= scansione valida ma con lacune dichiarate. - Ogni entità ha una confidence e un flag dedotto; l'evidenza indica file, righe e metodo.
8. Sicurezza e limiti
- Il repository analizzato è input non fidato: nessun codice eseguito, nessun MSBuild, percorsi confinati, symlink esterni ignorati. I file di segreti (
.env,*.pfx,*.pem,appsettings*.json) non vengono mai letti. - Database: solo metadati, mai i dati;
ApplicationIntent=ReadOnly; stringhe di connessione mai salvate né stampate. API solo su loopback. - Limiti: Web Forms e MVC 5 senza MSBuild lasciano riferimenti a
System.Webnon risolti (copertura «source» parziale); solo SQL Server; codice generato a build-time non visto; combinazioni di#ifnon esaustive.
9. Codici di uscita
0 ok · 1 errore generico · 2 configurazione non valida · 3 database non raggiungibile · 4 repository non valido · 5 scansione incompleta · 6 export fallito · 130 annullato (Ctrl+C).
10. Se qualcosa non va
si-engine: command not found: aggiungi$HOME/.dotnet/toolsalPATH.- Errore all'avvio sul runtime: installa l'ASP.NET Core Runtime 10.
workspace_not_initialized: eseguisi-engine init(o usa--workspace/SIE_HOME).invalid_repository: il percorso non esiste o non contiene soluzioni, progetti né file Web Forms.- Pagine Web Forms senza eventi o dati: guarda
si-engine scanHLe il warningwebforms.code_behind_not_found. - Log in
<workspace>/logs/; più dettaglio con-v debug(passi e durate) e-v trace(anche un messaggio per progetto e per tecnologia). Per un tempo lungo:si-engine scan -a <app> -v debug 2>&1 | tee scan.log.
Licenza: MIT.
Strumenti correlati
- AzDo — Azure DevOps CLI e server MCP
- JiraCli-Mcp — Jira CLI e server MCP
- SharpGuard — .NET SAST/SCA scanner di sicurezza
Versione 1.3.24
Novità rispetto alla 1.3.0:
- Repository misti (
.csproj+ Web Site senza progetto): il Web Site fuori dalle cartelle dei progetti è sintetizzato come progetto a parte (nome reso univoco con il suffisso.WebSitese coincide con un progetto) e il collegamento pagina → classe del data layer → stored procedure/tabella funziona anche senza database collegato. - Sicurezza e stato dell'export: i messaggi del parser T-SQL e il report di scansione sono mascherati prima di essere stampati o emessi; con entrambi gli export disabilitati
scanHLriportadisabled(nessun file, exit code invariato). - Nota di progetto multi-radice (nessun cambiamento di comportamento):
docs/adr/ADR-0009-repository-multi-root.mddescrive perché dichiarare più radici in un'applicazione non è stato fatto in questa serie e come farlo a passi (percorsi con prefisso, guardia per radice, fingerprint per radice). - Memoria nelle scansioni enormi: l'artefatto di stadio viene scritto già compresso (gzip) e verificato in streaming, senza mai tenere in memoria il documento JSON (centinaia di MB); con
-v debugl'analisi C# registra la memoria gestita e residente a ogni fase (Roslyn memory after ...). - T-SQL legacy: i moduli SQL (stored procedure, viste, funzioni, trigger) sono analizzati con l'impostazione QUOTED_IDENTIFIER con cui sono stati creati (
sys.sql_modules.uses_quoted_identifier) e con il livello di compatibilità del database; se non basta si prova l'impostazione opposta e poi i parser più vecchi, e ogni tentativo è nel warningdataaccess.module_parse_error(o nel warning informativodataaccess.module_parse_fallbackquando riesce dopo un ripiego). - Sicurezza dei percorsi: la cache dei controlli sui collegamenti simbolici (valida solo dentro un passaggio di discovery/analisi) è ora sicura con più thread (
Task.Run,Parallel) e con scope annidati; il file e la sua cartella immediata sono controllati a ogni lettura. - Precisione pagina → stored procedure: la chiamata attribuita al solo candidato (argomenti di tipo non risolto) ha una regola propria a 0,6 e un percorso che la attraversa è «possibile» nell'impatto (con tutti gli archi risolti resta «transitivo»); il nome di una stored procedure passato come costante a un helper che la esegue (un solo livello) dà l'accesso al chiamante.
- scanHL scrive anche i file: dopo la scansione esegue gli stessi export di
export humanedexport llmin<workspace>/output/<applicazione>/{human,llm}(-oper cambiare cartella,--no-exportper saltarli); se l'export fallisce la scansione resta salvata ed exit code 6. - Scansioni molto grandi: l'artefatto di stadio dei grafi di chiamate con centinaia di migliaia di archi resta in UTF-8 fino al salvataggio e l'heap è compattato dopo i moduli pesanti: una scansione con ~685.000 chiamate non esaurisce più la memoria.
- Progetti legacy non analizzati = lacuna «source»: senza
Analysis__AnalyzeLegacyProjects=trueil C# dei progetti non SDK-style è saltato e il report lo dichiara con il modo di abilitarlo;--excludeaccetta wildcard ed è applicato prima della lettura dei file;code.missing_referenceselenca i nomi non risolti più frequenti; le classi*_SERVICEin maiuscolo sono riconosciute. - Il pacchetto contiene un solo file di documentazione: questo README, in italiano e in inglese.
si-engine --helpelenca tutti i comandi con le opzioni, le variabili d'ambiente e le chiavi di configurazione da impostare prima di avviare il programma, gli id dei moduli e i codici di uscita.- Nuovo comando
app updateper cambiare un'applicazione già registrata (repository, database, descrizione, esclusioni) senza modificare a mano i file;lastScanIdnel riepilogo delle applicazioni (MCP e API); una scansione fallita non lascia righe parziali; il nome del Web Site alla radice è fisso (WebSite). - Stored procedure chiamate tramite helper: con un database collegato, una stringa o una costante uguale al nome di una stored procedure collega il metodo alla procedura (confidence 0,5), così pagine e classi arrivano alle tabelle anche quando la chiamata ADO.NET passa da un helper o da un data access block (AB#47).
- Pagine non collegate al database:
scanHLstampa «Pagine → database: N su M collegate» e il motivo delle altre; lo stesso dato (pageLinkage) è insie_get_overview(MCP) e nell'API. - «database is locked»: l'indice di ricerca si costruisce a blocchi e con un lock fra processi (una sessione lo costruisce, le altre aspettano), l'avvio dei comandi non chiede più il lock di scrittura, e l'errore ora è
database_lockedcon il suggerimento su cosa fare. - Più sessioni e più utenti: la scrittura di una scansione non blocca più il database per minuti (transazioni brevi, una scansione fallita non lascia nulla);
Storage__BusyTimeoutSecondsregola l'attesa del lock (default 30 s) eStorage__SharedAccess=truepermette a un gruppo di utenti di usare lo stesso workspace. - Più dettaglio con
-v debuge-v trace: durata di ogni passo della discovery, decisione di applicabilità e durata di ogni modulo, tempi per progetto di Roslyn, tempi di ogni query sul catalogo SQL Server e di ogni fase di scrittura della scansione (utile per capire dove va il tempo). - Una soluzione di Web Site (
.slnche elenca la cartella del sito, nessun.csproj) ora è riconosciuta; le stored procedure create conQUOTED_IDENTIFIER OFF(stringhe tra doppi apici) non danno più errori di parsing. - Si possono scansionare i Web Site ASP.NET senza
.sln/.csproj(soloweb.config+.aspx/.ascx/.master): le pagine sono trovate dai file e compare il warningdiscovery.website_without_project. Il progetto è sintetizzato dalla cartella del sito e il suo C# (App_Code, code-behind) è analizzato come per un progetto Web Forms.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
This package has no dependencies.
Package metadata and README rewritten in English for discoverability, package icon added. Lower memory on very large code bases.