bluetunax/Fed-Cascade

# 🦅 Fed Cascade v1.0 ## 📜 宣言 **联邦采购数据不是静态的。官方 API 提供的第一手答案很少是最终答案。** 每年，数百亿美元通过美国联邦机构、国防承包商和国际非政府组织流转。传统的仪表盘将这些数据奉为圭臬，不断覆盖其记录以显示资金的“当前”状态。 但对于 OSINT 分析师、记者和反腐败监督机构来说，真正重要的不仅仅是今天*存在什么*。真正重要的是**发生了什么变化**。旧合同被修改。奖励金额悄悄膨胀或缩水。组织被更名。补助金被追溯取消。 如果官方账本报告在 6 月份向主承包商支付了 1200 万美元，并在 12 月份悄悄地将其修改为 2700 万美元，大多数仪表盘将永远只会向您展示 2700 万美元。 **Fed Cascade 改变了这一点。** Fed Cascade 被构建为一个**“Git-for-Procurement” 版本控制系统**。它不仅提取数据，还会对数据进行快照、存储，并将未来数据与您不可变的基准线进行比较，以检测追溯性异常。通过揭示美国财政部过去和现在的官方记录之间的确切差异，Fed Cascade 将基础报告转化为可操作的时间情报。 ## 🚀 核心 OSINT 创新 ### 👁️‍🗨️ 监督引擎（时间情报） 该平台的核心王冠。该引擎不盲目信任实时 API，而是允许您设置历史“基准锚点”。当您执行后续的实时扫描时，Diff 引擎会自动检测： * **新增的资金管道：** 追溯注入的资金流或新解密的合同。 * **修改的值：** 悄然发生变化的现有奖励（例如，原始：1200 万美元 -> 当前：2700 万美元 -> 差异：+1500 万美元）。 * **删除的记录：** 已从 API 中被抹除的补助金或合同。 ### 🗄️ Git 风格账本与累加缓存 USAspending API 有着严格的速率限制，并需要严格的分类过滤。Fed Cascade 使用**安全累加合并（时间桶）**架构。它将新的实时 API 数据合并到您本地的 SQLite Factbook 中，确保您现有的离线记录免受错误删除的影响。您可以放心地构建一个 10 年期的不可变离线账本。 ### 🧠 并发全球扫描（实体搜索） Fed Cascade 依赖于 OSINT 风格的暴力破解架构：它会自动处理 USAspending.gov 所需的复杂多阶段 payload 路由，使用后台线程对原始 JSON 进行模糊搜索，在全球范围内寻找目标实体的任何踪迹，无缝合并国内和国际管道，且绝不会锁定 UI。 ### 🏛️ 宏观与微观剖析 * **宏观层（合同）：** 隔离通常授予主要营利性执行合作伙伴（即“环城公路匪帮”）的大型主合同、确定性合同和采购订单。 * **微观层（补助/贷款）：** 隔离下游财政援助，包括流向国际非政府组织、联合国机构和外国政府的项目补助、直接支付和贷款。 ### 🕵️‍♂️ 全球情报档案（Factbook） * **自动化画像：** 在您摄取数据时，Fed Cascade 会纯粹基于您的离线缓存，有机地为 Prime Contractor、Grantee、国家和行业构建 CIA Factbook 风格的档案。 * **行业名录：** 在全球范围内扫描原始的奖励描述，以寻找特定的业务集群（例如，网络安全、国防系统、全球健康、基础设施），并动态生成情报数据透视表。 ## 🏗️ 数据架构与方法论 数据直接通过异步 API 调用 (`httpx`) 从由美国财政部管理的 **USAspending.gov API v2** 获取。 ### 方法论的现实 追踪资金从联邦机构到 Prime Contractor 的过程很简单。追踪资金从该 Prime Contractor 到达最终目的地的过程却出了名的困难。标准的国际管道通常如下所示： `USAID → Prime Contractor / INGO → Sub-Awardee / Local Partner` *免责声明：Fed Cascade 追踪资金流向由 USAspending 公布的最远端可**观察** Prime 接收方。出于操作安全的考虑，最终子承包商的端到端可见性通常会被报告机构掩盖或延迟。Fed Cascade 绘制公开声明的内容，并监视这些声明是否发生变化。* ## 💻 安装与设置 Fed Cascade v1.0 需要 **Python 3.10+**。 ### 1. 克隆仓库 ``` git clone https://github.com/bluetunax/fed-cascade.git cd fed-cascade ``` ### 2. 安装依赖 **选项 A：使用 Conda（推荐）** ``` conda env create -f environment.yml conda activate fed-cascade ``` **选项 B：使用 Pip / Virtualenv** ``` # Windows python -m venv venv venv\Scripts\activate # Mac/Linux python3 -m venv venv source venv/bin/activate pip install -r requirements.txt ``` ### 3. 初始化引擎 ``` python main.py ``` *应用程序会在首次运行时自动初始化本地的 `fed_cascade.db` SQLite 数据库。* **访问地址：** [http://127.0.0.1:5000](http://127.0.0.1:5000) ## 🗺️ 系统蓝图 ``` fed-cascade/ ├── fed_cascade.db # Local SQLite ledger (Auto-generated) ├── config.py # Pydantic Global Settings Management ├── main.py # FastAPI App & ASGI Server ├── models.py # SQLModel database schemas (Inc. LedgerChange) ├── data_engine.py # Async API fetchers & Taxonomy Router ├── db_manager.py # DB connection pooling, bulk inserts, exports ├── routers/ # Modular FastAPI Endpoints │ ├── dashboard.py # Single-Year flows, JSON exports, wiping │ ├── activities.py # Text-based award description search │ ├── profiles.py # 5-Year Pipelines & Entity dossiers │ ├── intelligence.py # Global search & Bibliography factbook │ ├── version_control.py # Diff engine & Ledger Hub merging │ └── changes.py # Watchdog Volatility Dashboard ├── services/ │ ├── charts.py # Plotly dynamic visual generation │ ├── intelligence.py # Offline Factbook aggregation logic │ ├── entity_normalization.py # Federal Entity alias mapping and cleaning │ ├── state.py # Real-time HTMX loading HUD state manager │ └── version_control.py # Diff calculation & Watchdog impact scoring ├── static/ │ └── style.css # Tailwind overrides & Vanilla Datatables └── templates/ # HTMX-powered Jinja2 UI Components ``` ## 🛠️ 快速入门指南 1. **定位目标区域：** 打开 **Country Snapshot**，输入 ISO-3 代码（例如 `UKR`, `SDN`, `YEM`）和年份，然后点击 *Execute Query*。 2. **锁定锚点：** 导航至 **Ledger Version Control**。找到您的新快照并点击 **Set Base**。 3. **等待并重新扫描：** 几周或几个月后，返回到 Country Snapshot。勾选 **Force Live API Update** 框并再次执行查询。 4. **追踪波动性：** 系统将悄悄提取实时数据，绕过严格的 USAspending 分类规则，执行安全累加合并以保护您的本地缓存，并将检测到的任何差异发送到 **Watchdog Dashboard**。导航至该页面以查看并打印追溯性异常。 5. **协同合作：** 导航至 **Settings**，将您整个不可变的账本导出为便携式 JSON 文件，以便与其他分析师分享。 ## 📄 许可证 **MIT 许可证** 版权所有 (c) 2026 Fed Cascade 特此免费授予任何获得本软件副本及相关文档文件（下称“软件”）的人不受限制地处置该软件的权利，包括不受限制地使用、复制、修改、合并、发布、分发、转授许可和/或贩卖该软件副本的权利。 上述版权声明和本许可声明应包含在所有的软件副本或实质性的部分中。 该软件“按原样”提供，不提供任何明示或暗示的保证，包括但不限于适销性、特定用途适用性和非侵权性的保证。在任何情况下，对于因软件或软件的使用或其他交易引起的、与之相关的、由其导致的索赔、损害或其他责任，作者或版权持有人均不承担任何责任。 SOFTWARE.

标签：AV绕过, DFIR, ESC4, FastAPI, OSINT, SQLite, 后端开发, 安全可观测性, 政府支出分析, 数据追踪, 时序数据, 版本控制, 运行时操纵, 逆向工具