{"id":48308434,"url":"https://github.com/hmlendea/system-info-api","last_synced_at":"2026-04-05T00:12:35.005Z","repository":{"id":344819066,"uuid":"1183188996","full_name":"hmlendea/system-info-api","owner":"hmlendea","description":"Lightweight self-hosted API for exposing system metrics and host diagnostics (ideal for monitoring and automation).","archived":false,"fork":false,"pushed_at":"2026-03-29T13:35:07.000Z","size":52,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-29T16:37:41.760Z","etag":null,"topics":["api","csharp","dotnet","monitoring","rest","rest-api","self-hosted","system-info"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hmlendea.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":null,"patreon":"hmlendea","open_collective":null,"ko_fi":"hmlendea","tidelift":null,"community_bridge":null,"liberapay":"HMlendea","issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":"hmlendea","thanks_dev":null,"custom":"https://hmlendea.go.ro/fund.html"}},"created_at":"2026-03-16T11:08:42.000Z","updated_at":"2026-03-29T13:33:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hmlendea/system-info-api","commit_stats":null,"previous_names":["hmlendea/system-info-api"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/hmlendea/system-info-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmlendea%2Fsystem-info-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmlendea%2Fsystem-info-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmlendea%2Fsystem-info-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmlendea%2Fsystem-info-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hmlendea","download_url":"https://codeload.github.com/hmlendea/system-info-api/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmlendea%2Fsystem-info-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31419555,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T20:09:54.854Z","status":"ssl_error","status_checked_at":"2026-04-04T20:09:44.350Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","csharp","dotnet","monitoring","rest","rest-api","self-hosted","system-info"],"created_at":"2026-04-05T00:12:34.419Z","updated_at":"2026-04-05T00:12:34.989Z","avatar_url":"https://github.com/hmlendea.png","language":"C#","funding_links":["https://patreon.com/hmlendea","https://ko-fi.com/hmlendea","https://liberapay.com/HMlendea","https://buymeacoffee.com/hmlendea","https://hmlendea.go.ro/fund.html"],"categories":[],"sub_categories":[],"readme":"[![Donate](https://img.shields.io/badge/-%E2%99%A5%20Donate-%23ff69b4)](https://hmlendea.go.ro/fund.html) [![Latest GitHub release](https://img.shields.io/github/v/release/hmlendea/system-info-api)](https://github.com/hmlendea/system-info-api/releases/latest) [![Build Status](https://github.com/hmlendea/system-info-api/actions/workflows/dotnet.yml/badge.svg)](https://github.com/hmlendea/system-info-api/actions/workflows/dotnet.yml)\n\n# System Info API\n\n## About\n\nSimple ASP.NET Core REST API that exposes basic information about the host machine.\n\nThe service currently returns three categories of data:\n\n- system information\n- network information\n- regional information\n\nThis project is intended for lightweight infrastructure tooling, status dashboards, system inventory jobs, and internal automation where a small authenticated HTTP endpoint is easier to integrate than shelling into a host.\n\n## Features\n\n- Returns operating system name, kernel version, architecture, hostname, and uptime\n- Returns network information, including public IP address and hostname\n- Returns regional information, including current system time and local time zone\n- Supports Linux distro detection\n- Supports ARM and ARM64 architecture reporting in addition to x86 and x64\n- Signs responses using HMAC\n- Protects requests with API-key authorization and replay-protection middleware\n- Uses structured logging through `NuciLog`\n\n## Technology Stack\n\n- .NET 10.0\n- ASP.NET Core Web API\n- `NuciAPI`\n- `NuciAPI.Controllers`\n- `NuciAPI.Middleware`\n- `NuciLog`\n- `NuciSecurity.HMAC`\n- `NuciWeb.HTTP`\n\n## Project Structure\n\n- `Api/Controllers` contains HTTP controllers\n- `Api/Mapping` contains mappings from domain models to response DTOs\n- `Api/Requests` contains API request models\n- `Api/Responses` contains response envelopes and response objects\n- `Configuration` contains configuration binding models\n- `Logging` contains operation and log key definitions\n- `Service` contains business logic and domain models\n\n## Endpoint\n\nThe API currently exposes a single endpoint:\n\n- `GET /SystemInfo`\n\nThe route comes from the controller name, so the default path is exactly `/SystemInfo`.\n\n## Returned Data\n\nThe response contains three top-level objects.\n\n### System\n\n`system` contains host operating-system data:\n\n- `os`: operating system name\n- `kernel`: kernel version or kernel-like OS descriptor\n- `arch`: architecture string such as `x86`, `x64`, `arm`, or `arm64`\n- `hostname`: local machine name\n- `uptime`: host uptime in seconds\n\nPlatform-specific behavior:\n\n- On Linux, `os` is read from `PRETTY_NAME` in `/etc/os-release` when available\n- On Linux, `kernel` is read from `/proc/sys/kernel/osrelease`\n- On other platforms, the implementation falls back to `RuntimeInformation.OSDescription`\n\n### Network\n\n`network` currently contains:\n\n- `public_ip`: public IP address as resolved by `NuciWeb.HTTP`\n- `hostname`: local machine name\n\nNote: `public_ip` depends on outbound network connectivity\n\n### Region\n\n`region` contains:\n\n- `system_time`: current local system time in ISO 8601 format\n- `time_zone`: local time zone string from `TimeZoneInfo.Local`\n\nNotes:\n\n- `system_time` is generated with the `o` format specifier, so it is an ISO 8601 round-trip timestamp\n- `time_zone` is platform-dependent because .NET time zone identifiers differ between Linux and Windows\n\n## Example Response Shape\n\nThe exact outer envelope is provided by the `NuciAPI` base response type, but the payload produced by this project has the following structure:\n\n```json\n{\n\t\"system\": {\n\t\t\"os\": \"Arch Linux\",\n\t\t\"kernel\": \"6.19.6-arch1-1\",\n\t\t\"arch\": \"x64\",\n\t\t\"hostname\": \"my-host\",\n\t\t\"uptime\": 123456\n\t},\n\t\"network\": {\n\t\t\"public_ip\": \"203.0.113.10\",\n\t\t\"hostname\": \"my-host\"\n\t},\n\t\"region\": {\n\t\t\"system_time\": \"2026-03-16T13:47:09.3182334+02:00\",\n\t\t\"time_zone\": \"(UTC+02:00) Eastern European Time (Bucharest)\"\n\t}\n}\n```\n\nNote: The upstream `NuciAPI` response envelope adds metadata fields, and those will appear around this payload.\n\n## Security\n\nThe application is configured with the following security-related middleware and behavior:\n\n- request header validation\n- replay protection\n- API-key authorization\n- HMAC response signing\n\nThe endpoint uses the configured API key through `NuciApiAuthorisation.ApiKey(...)`, and the response is signed using the configured HMAC signing key.\n\nThis means the service is intended for trusted internal clients that know:\n\n- the correct API key\n- the expected request format required by the `NuciAPI` middleware stack\n- how to validate the response signature if needed\n\n## Configuration\n\nConfiguration is bound from `appsettings.json` into `SecuritySettings` and `NuciLoggerSettings`.\n\n### appsettings.json\n\n```json\n{\n\t\"securitySettings\": {\n\t\t\"apiKey\": \"[[SYSTEM_INFO_API_KEY]]\",\n\t\t\"hmacSigningKey\": \"[[SYSTEM_INFO_HMAC_SIGNING_KEY]]\"\n\t},\n    \"nuciLoggerSettings\": {\n        \"logFilePath\": \"logfile.log\",\n        \"isFileOutputEnabled\": true\n    }\n}\n```\n\n### Required Settings\n\n- `securitySettings.apiKey`: API key required by the endpoint authorization layer\n- `securitySettings.hmacSigningKey`: secret used to sign responses\n\n### Environment Variables\n\nBecause the application uses the default ASP.NET Core host builder, these values can also be supplied through environment variables:\n\n```bash\nSecuritySettings__ApiKey=your-api-key\nSecuritySettings__HmacSigningKey=your-hmac-key\n```\n\nUsing environment variables or a secrets manager is preferable to storing real secrets directly in `appsettings.json`.\n\n## Running Locally\n\n### Prerequisites\n\n- .NET 10.0 SDK\n\n### Restore Dependencies\n\n```bash\ndotnet restore\n```\n\n### Run the API\n\n```bash\ndotnet run\n```\n\nBy default, ASP.NET Core will start the application using the URLs configured by the runtime environment.\n\n### Build the Project\n\n```bash\ndotnet build\n```\n\n### Publish the Project\n\nThe repository includes a helper script:\n\n```bash\n./release.sh 1.2.3\n```\n\nThe script downloads and executes an external deployment script for .NET 10.0 releases.\n\nBefore using it in production, review the referenced script and make sure that executing a remote script matches your deployment policy.\n\n## Implementation Notes\n\n### Operating System Detection\n\nThe service tries to return a user-friendly operating-system name instead of the low-level platform/version tuple.\n\n- Linux: reads `PRETTY_NAME` from `/etc/os-release`\n- other platforms: falls back to `RuntimeInformation.OSDescription`\n\n### Kernel Detection\n\n- Linux: reads `/proc/sys/kernel/osrelease`\n- other platforms: currently falls back to `RuntimeInformation.OSDescription`\n\n### Architecture Detection\n\nArchitecture is derived from `RuntimeInformation.OSArchitecture` and normalized to lower-case API values:\n\n- `x86`\n- `x64`\n- `arm`\n- `arm64`\n\n### Uptime Calculation\n\nUptime is calculated from `Environment.TickCount64` and returned as whole seconds.\n\nThis is simple and portable, but it reflects process-environment tick timing rather than a platform-specific uptime command output.\n\n## Limitations\n\n- only one HTTP endpoint is currently exposed\n- the network section does not currently expose local IP addresses\n- public IP discovery depends on external network reachability\n- time zone identifiers are platform-dependent\n- the exact authentication header contract is defined by the `NuciAPI` libraries, not redefined in this repository\n\n## Development Notes\n\nImportant service registrations:\n\n- `ISystemInfoService` -\u003e `SystemInfoService`\n- `ILogger` -\u003e `NuciLogger`\n\nImportant middleware enabled in startup:\n\n- exception handling middleware from `NuciAPI`\n- HTTPS redirection\n- static file support\n- header validation\n- replay protection\n- authorization\n\n## Target Framework\n\nThe current package targets `.NET 10.0`.\n\n## License\n\nThis project is licensed under the `GNU General Public License v3.0` or later. See [LICENSE](./LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhmlendea%2Fsystem-info-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhmlendea%2Fsystem-info-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhmlendea%2Fsystem-info-api/lists"}