# HostGuard AI 主机安全审计

**Repository Path**: cncsrf/hostguard-ai

## Basic Information

- **Project Name**: HostGuard AI 主机安全审计
- **Description**: HostGuard AI 主机安全审计：基于AI的主机安全合规检测工具，自动识别配置风险与漏洞，助力企业实现自动化安全审计与防护。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-03
- **Last Updated**: 2026-09-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HostGuard AI 主机安全审计系统

> 🛡️ 面向企业内网的主机安全审计与漏洞管理平台：自动发现资产、基线检查、同步 NVD 漏洞情报并做风险关联分析。

[![Python](https://img.shields.io/badge/Python-3.12-blue)](https://python.org)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-green)](https://fastapi.tiangolo.com)
[![Docker](https://img.shields.io/badge/Docker-Compose-green)](https://docs.docker.com/compose/)
[![License](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)

HostGuard AI 通过 Agent-less 方式采集内网主机数据，支持 **SSH 与 MCP Server 双通道**：既可用 SSH 账号/密钥批量纳管主机，也可对接 MCP Server 拉取资产与运行状态；自动发现服务器资产，识别已安装软件及版本，并与 NVD 同步的 CVE 情报进行匹配，帮助安全团队快速定位受影响资产、评估风险等级并跟踪修复进度。

## 功能特性

| 功能 | 说明 |
|------|------|
| **资产发现** | SSH 账号/密钥 与 **MCP Server** 双通道采集主机资产，自动采集系统信息、用户、服务、软件包 |
| **漏洞情报** | 配置 NVD API Key，定时/手动同步 CVE 数据，按 CPE 规则匹配资产版本 |
| **风险关联** | 资产详情页直接展示该主机/软件关联的 CVE 风险与严重等级分布 |
| **基线检查** | 覆盖账号口令、SSH 配置、SUID/SGID、systemd、登录日志等多维度安全基线 |
| **漏洞扫描** | 集成 nmap-scanner-web（端口 8090）做主机端口与服务扫描 |
| **Web 控制台** | 原生 JS + Bootstrap 单页管理界面，覆盖资产、漏洞、任务、报表等模块 |

## 技术栈

- **后端**：Python 3.12 + FastAPI + SQLAlchemy + SQLite
- **前端**：HTML5 + Bootstrap 5 + 原生 JavaScript（纯静态文件，无构建步骤）
- **任务调度**：APScheduler
- **容器化**：Docker + Docker Compose（多阶段构建，运行时镜像约 240MB，不含编译器）

## 快速开始

### 方式一：脚本部署

```bash
git clone https://gitee.com/cncsrf/hostguard-ai.git
cd hostguard-ai
sudo bash deploy.sh
```

- 访问：http://服务器IP:8080
- 默认账号：`admin` / `admin@123`
- 兼容主流 Linux 发行版，已在 Ubuntu 24.04 上完整测试通过

### 方式二：Docker 部署（推荐）

```bash
docker run -d \
  --name hostguard-backend \
  --restart unless-stopped \
  -p 8000:8000 \
  -v hg-data:/app/data \
  -v hg-logs:/app/logs \
  -e TZ=Asia/Shanghai \
  ad80a1/hostguard-ai:backend

docker run -d \
  --name hostguard-frontend \
  --restart unless-stopped \
  -p 8080:80 \
  -e TZ=Asia/Shanghai \
  -e API_PORT=8000 \
  ad80a1/hostguard-ai:frontend
```

- 访问：http://服务器IP:8080
- 默认账号：`admin` / `admin@123`
- 兼容任意已安装 Docker 的 Linux 发行版

> 高级配置（自定义端口、NVD API Key、自定义 `.env` 等）请见 [backend/docs/development.md](backend/docs/development.md)，懂 Docker 的用户可自行调整。

## 在线端口扫描（8090）

本项目支持调用独立的 [nmap-scanner-web](https://gitee.com/cncsrf/nmap-scanner-web) 服务进行主机端口扫描，扫描结果自动关联到对应主机资产。

- 默认服务端口：`8090`
- 需先部署 nmap-scanner-web，再在 HostGuard 的「系统设置」中配置其地址。

## 演示截图

### 系统首页

![HostGuard 首页](./docs/screenshots/hostguard-home.jpg)

### 主机管理

![主机管理](./docs/screenshots/hosts-manage.jpg)

### 资产指纹

![资产指纹](./docs/screenshots/asset-fingerprint.jpg)

## 项目结构

```
hostguard-ai/
├── backend/                 # FastAPI 后端
│   ├── app/
│   │   ├── api/v1/endpoints/   # 接口路由（主机/漏洞/资产/任务/报表/MCP…）
│   │   ├── auth/               # JWT 鉴权
│   │   ├── services/           # 业务服务（AI 分析、资产、审计…）
│   │   ├── config.py           # 配置加载（pydantic-settings）
│   │   ├── database.py         # SQLite 初始化与连接
│   │   ├── main.py             # FastAPI 应用入口
│   │   ├── models.py           # ORM 模型
│   │   ├── schemas.py          # Pydantic 模型
│   │   └── run.py              # 启动脚本
│   ├── alembic/               # 数据库迁移（历史留档，运行期由 create_all 建表）
│   ├── data/                  # SQLite 数据目录（运行时生成）
│   ├── logs/                  # 日志目录
│   ├── requirements.txt
│   ├── Dockerfile             # 多阶段构建（运行时镜像不含编译器）
│   └── docker-entrypoint.sh   # 容器入口（缺 .env 时自动由 .env.example 生成）
├── frontend/                 # 静态前端（原生 JS + Bootstrap）
│   ├── index.html
│   ├── *.js / *.css           # 各页面与公共脚本
│   ├── Dockerfile             # nginx:alpine 托管
│   └── docker-entrypoint.sh
├── scripts/
│   ├── collect_ir.sh          # 推送目标主机的入侵采集脚本
│   └── make-release.sh        # 离线发布包打包
├── docs/
│   └── screenshots/           # 演示截图
├── docker-compose.yml         # 容器编排（引用 Docker Hub 预构建镜像）
├── deploy.sh                  # 脚本一键部署
├── uninstall.sh               # 脚本卸载
├── .dockerignore
├── .gitignore
└── README.md
```

## 开发与贡献

详细的开发说明、API 接口与部署排错请查看 [backend/docs/development.md](backend/docs/development.md)。

欢迎提交 Issue 或 PR。

## License

MIT