si-engine 1.3.24

dotnet tool install --global si-engine --version 1.3.24
                    
This package contains a .NET tool you can call from the shell/command line.
dotnet new tool-manifest
                    
if you are setting up this repo
dotnet tool install --local si-engine --version 1.3.24
                    
This package contains a .NET tool you can call from the shell/command line.
#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>, otherwise SIE_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/.master file, also next to .csproj projects when outside their folders). Otherwise the error is invalid_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 knowledge also knowledge.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

  • --incremental reuses 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.Web references unresolved (partial «source» coverage); SQL Server only; code generated at build time is not seen; #if combinations 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/tools to PATH.
  • Runtime error at startup: install the ASP.NET Core Runtime 10.
  • workspace_not_initialized: run si-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 scanHL and the webforms.code_behind_not_found warning.
  • 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.

  • 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 scanHL reports disabled (no files, exit code unchanged).

  • Multi-root design note (no behaviour change): docs/adr/ADR-0009-repository-multi-root.md explains 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 debug the 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 the dataaccess.module_parse_error warning (or in the informational dataaccess.module_parse_fallback warning 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 .WebSite suffix 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 human and export llm into <workspace>/output/<application>/{human,llm} (-o to change the folder, --no-export to 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=true the C# of non SDK-style projects is skipped and the report says so and how to enable it; --exclude accepts wildcards and is applied before any file is read; code.missing_references lists the most frequent unresolved names; upper-case *_SERVICE classes are recognised.

  • The package ships a single documentation file: this README, in Italian and English.

  • si-engine --help lists 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 update to change an already registered application (repository, database, description, exclusions) without editing files by hand; lastScanId in 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: scanHL prints «Pagine → database: N of M linked» with the reason for the others; the same data (pageLinkage) is in sie_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_locked with 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__BusyTimeoutSeconds sets how long to wait for the lock (default 30 s) and Storage__SharedAccess=true lets a group of users share one workspace.

  • More detail with -v debug and -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 (.sln listing the site folder, no .csproj) is now recognised; stored procedures created with QUOTED_IDENTIFIER OFF (double-quoted strings) no longer give parse errors.

  • ASP.NET Web Sites without .sln/.csproj can be scanned (only web.config + .aspx/.ascx/.master): pages are discovered from the files and the warning discovery.website_without_project is 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>, altrimenti SIE_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 .csproj se fuori dalle loro cartelle). Altrimenti errore invalid_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 knowledge anche knowledge.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

  • --incremental riusa 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.Web non risolti (copertura «source» parziale); solo SQL Server; codice generato a build-time non visto; combinazioni di #if non 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/tools al PATH.
  • Errore all'avvio sul runtime: installa l'ASP.NET Core Runtime 10.
  • workspace_not_initialized: esegui si-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 scanHL e il warning webforms.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 .WebSite se 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 scanHL riporta disabled (nessun file, exit code invariato).
  • Nota di progetto multi-radice (nessun cambiamento di comportamento): docs/adr/ADR-0009-repository-multi-root.md descrive 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 debug l'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 warning dataaccess.module_parse_error (o nel warning informativo dataaccess.module_parse_fallback quando 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 human ed export llm in <workspace>/output/<applicazione>/{human,llm} (-o per cambiare cartella, --no-export per 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=true il C# dei progetti non SDK-style è saltato e il report lo dichiara con il modo di abilitarlo; --exclude accetta wildcard ed è applicato prima della lettura dei file; code.missing_references elenca i nomi non risolti più frequenti; le classi *_SERVICE in maiuscolo sono riconosciute.
  • Il pacchetto contiene un solo file di documentazione: questo README, in italiano e in inglese.
  • si-engine --help elenca 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 update per cambiare un'applicazione già registrata (repository, database, descrizione, esclusioni) senza modificare a mano i file; lastScanId nel 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: scanHL stampa «Pagine → database: N su M collegate» e il motivo delle altre; lo stesso dato (pageLinkage) è in sie_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_locked con 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__BusyTimeoutSeconds regola l'attesa del lock (default 30 s) e Storage__SharedAccess=true permette a un gruppo di utenti di usare lo stesso workspace.
  • Più dettaglio con -v debug e -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 (.sln che elenca la cartella del sito, nessun .csproj) ora è riconosciuta; le stored procedure create con QUOTED_IDENTIFIER OFF (stringhe tra doppi apici) non danno più errori di parsing.
  • Si possono scansionare i Web Site ASP.NET senza .sln/.csproj (solo web.config + .aspx/.ascx/.master): le pagine sono trovate dai file e compare il warning discovery.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 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.

Version Downloads Last Updated
1.3.24 60 11/14/2026
1.3.23 51 11/12/2026
1.3.8 77 11/11/2026
1.3.5 83 11/11/2026
1.3.0 88 11/10/2026
1.2.2 95 11/5/2026
1.1.0 107 11/4/2026

Package metadata and README rewritten in English for discoverability, package icon added. Lower memory on very large code bases.