osquery 日志直连 AWS:Kinesis Streams 与 Firehose Logger 插件配置与原理详解 📅 发布时间:2026/9/20 21:41:48 👁 浏览次数: 观测代理网络安全【免费下载链接】osquerySQL powered operating system instrumentation, monitoring, and analytics.项目地址https://gitcode.com/gh_mirrors/os/osquery点击查看免费下载从 osquery 1.7.4 版本开始osqueryd可以将查询结果与状态日志直接写入 Amazon AWS 的 Kinesis Streams数据流和 Kinesis Firehose数据投递流从而在部署中省去一个独立的日志转发守护进程。本文以 docs/wiki/deployment/aws-logging.md 为主线结合仓库内aws_kinesis、aws_firehose两个 logger 插件的源码实现系统讲解它们的启用方式、全部配置项、AWS 凭证解析顺序以及底层批量缓冲、分片与重试机制帮助你在真实环境中正确落地这套方案。两个插件是什么aws_kinesis 与 aws_firehoseosquery 的日志系统通过logger_plugin标志选择插件AWS 相关日志功能由两个独立的 logger 插件提供aws_kinesis将日志写入 Amazon Kinesis Data Streams适用于需要自行消费数据流、按 shard 处理的场景aws_firehose将日志写入 Amazon Kinesis Data Firehose适合直接把日志投递到 S3、Redshift、Elasticsearch 等下游目标。两个插件在源码中通过 REGISTER 宏 与 REGISTER 宏 注册到logger注册表因此可以像其他 logger 插件一样通过--logger-pluginaws_kinesis,aws_firehose同时启用两者多个 logger 插件之间用逗号分隔。启用后插件会初始化 AWS SDK、创建对应的 AWS 客户端并把转发线程注册到 osquery 的 Dispatcher 调度器中见 aws_kinesis.cpp 与 aws_firehose.cpp。两个插件共享的 AWS 配置标志aws_kinesis与aws_firehose共用同一套 AWS 凭证、区域与代理配置。所有标志既可以作为 CLI 参数传入也可以写入配置文件配置文件中的options段以下是完整清单标志说明--aws_access_key_idAWS access key ID 覆盖值--aws_profile_name用于认证与区域配置的 AWS config profile 名--aws_regionAWS 区域覆盖值--aws_secret_access_keyAWS secret access key 覆盖值--aws_sts_arn_roleAWS STS assume role 的 ARN--aws_sts_regionAWS STS assume role 区域--aws_sts_session_nameAWS STS session 名称--aws_sts_timeoutAWS STS 临时凭证有效期秒取值范围 900–3600--aws_enable_proxy是否在 AWS 客户端配置中启用 HTTP/HTTPS 代理true 或 false--aws_proxy_scheme代理使用的 HTTP 协议http 或 https--aws_proxy_host代理主机--aws_proxy_port代理端口--aws_proxy_username代理用户名--aws_proxy_password代理密码这些标志的默认值可以在 aws_util.cpp 中逐一确认。有几点值得注意--aws_sts_session_name默认值为default--aws_sts_timeout默认值为3600代理相关配置只有在--aws_enable_proxytrue时才会被真正应用setAWSProxy是一个 no-op且--aws_proxy_scheme默认是https仓库中还额外提供--aws_session_token直接提供 STS session token、--aws_debug开启 AWS SDK 调试日志、--aws_enforce_fips强制所有服务使用 FIPS 端点以及一组 IMDSv2 相关标志aws_imdsv2_request_attempts、aws_imdsv2_request_interval、aws_disable_imdsv1_fallback这些在官方部署文档中未列出但在源码中均可用。AWS 凭证与区域的解析顺序当 osquery 需要访问 AWS 时会按照以下顺序查找凭证与区域配置配置标志对于区域优先使用服务级标志aws_sts_region、aws_kinesis_region、aws_firehose_region未设置时回退到aws_regionAWS config 文件中的 profile仅在指定了--aws_profile_name时;环境变量AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEYAWS config 文件中的defaultprofileEC2 Instance Metadata Service 中的 profile。该顺序与源码中OsqueryAWSCredentialsProviderChain的构建逻辑完全一致aws_util.cpp 按顺序依次挂载了 STS 凭证提供者仅在设置了aws_session_token或aws_sts_arn_role时加入、基于 osquery 标志的OsqueryFlagsAWSCredentialsProvider、指定的 profile、环境变量、默认 profile 以及InstanceProfileCredentialsProvider。区域的解析则由getAWSRegion实现aws_util.cpp 会先看传入的服务级区域与aws_region标志其次读取 profile 文件中的region字段最后回退到默认区域us-east-1。值得注意的是区域名会与源码内置的合法区域列表aws_util.cpp做校验非法区域名会导致插件初始化失败。通过 STS Assume Role 使用临时凭证所有 STS 相关标志都是可选的。但只要设置了aws_sts_arn_roleosquery 就会通过 AWS Security Token Service会先检查aws_session_token是否已直接提供有则直接使用否则调用 STS 客户端的AssumeRole以aws_sts_arn_role作为 RoleArn、aws_sts_session_name作为 RoleSessionName、aws_sts_timeout作为 DurationSeconds将取回的临时凭证缓存并在token_expire_time_到期即当前时间加上aws_sts_timeout后自动重新获取。此外源码还实现了对 EC2 Instance Metadata Service 的 IMDSv2 支持getIMDSTokenaws_util.cpp会先通过 PUT 请求获取 IMDSv2 token失败时可回退到 IMDSv1除非aws_disable_imdsv1_fallback被打开。配置 Kinesis Streamsaws_kinesis向 Kinesis Streams 写日志时必须指定流名称并可调节刷新周期--aws_kinesis_streamKinesis stream 名称必填。源码中 internalSetup 会检查该标志为空时直接返回错误Stream name must be specified with --aws_kinesis_stream--aws_kinesis_period向 Kinesis 刷新日志的间隔秒数默认10定义于 aws_kinesis.cpp。分区键与 shard 负载均衡--aws_kinesis_random_partition_key默认false控制分区键的生成方式设为false时osquery 使用本机 host identifier 作为每条记录的 partition key见 aws_kinesis.cpp即同一台主机的日志始终落在同一 shard保证按主机聚合处理的一致性设为true时每条记录都会生成一个随机 UUID 作为分区键aws_kinesis.cpp使日志在多 shard 的流上均匀分布、实现负载均衡。文档特别强调开启随机分区键后每台主机的日志会被分散到各个 shard如果你需要同一主机的日志始终由同一 shard 处理就不要开启此选项。自定义端点与区域--aws_kinesis_endpoint为非 AWS 的 Kinesis 兼容实现指定自定义端点。开启后插件在创建客户端时使用endpointOverride见 aws_util.cpp--aws_kinesis_region当目标区域与aws_region或 profile 文件中的默认区域不同时使用其优先级高于aws_region源码注释明确说明 This takes precedence over the aws_region flag见 aws_kinesis.cpp。另外Kinesis 插件还提供一个文档中未提及的标志--aws_kinesis_disable_log_status默认false即状态日志ERROR/WARNING/INFO默认会被一并发送置为true后可关闭状态日志处理见usesLogStatus()aws_kinesis.cpp。配置 Kinesis Firehoseaws_firehoseFirehose 插件的配置方式与 Kinesis 类似--aws_firehose_streamFirehose delivery stream 名称必填。internalSetup 在为空时会返回Stream name must be specified with --aws_firehose_stream--aws_firehose_period向 Firehose 刷新日志的间隔秒数默认10定义于 aws_firehose.cpp--aws_firehose_endpoint为非 AWS Firehose 兼容实现指定自定义端点--aws_firehose_region当区域与默认区域不同时使用优先级高于aws_region。Firehose 插件始终启用状态日志发送usesLogStatus()固定返回true见 aws_firehose.h这一点与 Kinesis 插件可以通过标志关闭不同。示例配置文件下面的 JSON 配置同时启用了两个插件所需的参数查询结果写入foo_streamKinesis投递流为bar_delivery_streamFirehose凭证与区域通过options段直接指定{ options: { host_identifier: hostname, schedule_splay_percent: 10, aws_kinesis_stream: foo_stream, aws_firehose_stream: bar_delivery_stream, aws_access_key_id: ACCESS_KEY, aws_secret_access_key: SECRET_KEY, aws_region: us-east-1 }, schedule: { time: { query: SELECT * FROM time;, interval: 2, removed: false } } }配置中同时出现了aws_kinesis_stream与aws_firehose_stream配合--logger-pluginaws_kinesis,aws_firehose即可让 osquery 同时向两类 AWS 服务投递日志。schedule段中的查询会周期性执行其输出即被送入上述 logger 插件。底层机制批量缓冲、协议上限与重试两个插件都继承自同一个模板基类AwsLogForwarderaws_log_forwarder.h其下再继承 osquery 通用的BufferedLogForwarderbuffered.h。因此日志并不是逐条即时发送的而是先在 osquery 数据库中缓冲由转发线程按aws_kinesis_period/aws_firehose_period周期性地批量取出并发送。理解这一点对评估日志延迟非常重要。批量组织与记录上限consumeDataAndGenerateBatchesaws_log_forwarder.h负责把缓冲的日志切分成一个或多个批次并遵循每个插件声明的协议上限。两个插件的具体上限如下可在各自源文件确认上限项aws_kinesisaws_firehose单条记录最大字节1000000 - 2561MB 减分区键上限10000001MB单批最大记录数500500单批最大字节50000004000000最大重试次数100100初始重试延迟3000ms3000ms是否追加换行符否是Firehose 插件会为每条记录追加\n换行符appendNewlineSeparators()返回true而 Kinesis 不追加。此外发送前每条记录都会通过appendLogTypeToJsonaws_util.cpp被注入一个log_typeJSON 字段取值为result或status若记录不是合法 JSON会被丢弃并记录错误日志这一行为与 TLS logger 插件保持一致见 aws_log_forwarder.h。超过 1MB 的记录会被拒收注意Kinesis 服务对单条记录有 1MB 的大小上限。超过该上限的结果日志会被 Kinesis 服务拒绝因此osqueryd不会转发它们。实际上插件自身在组批阶段就会把超过getMaxBytesPerRecord()的记录直接标记为discarded丢弃并写入错误日志而不是发给 AWSaws_log_forwarder.h。对于超大记录建议在查询侧控制返回列的数量或长度避免产生超限日志。发送与重试策略sendBatchaws_log_forwarder.h实现了带重试的发送循环每次请求失败整体请求失败或部分记录失败都会重试重试间隔为初始延迟 retry * 1000ms即第 1 次重试延迟 3000ms之后每次递增 1000ms最多重试100次重试时会从批次中剔除已经发送成功的记录以避免重复。若 osquery 正在关闭发送会立即中止并返回失败以便在下次启动时重新尝试这些未发出的批次aws_log_forwarder.h。彻底失败重试耗尽的批次会被转储到本地错误日志供管理员事后排查。单元测试 aws_kinesis_logger_tests.cpp 用自定义的DummyLogForwarder验证了这套组批与发送逻辑测试中将上限刻意调小为单记录 80 字节、单批 3 条/128 字节以覆盖边界情况可作为理解批量行为的参考。使用前提与注意事项构建依赖这两个插件依赖 AWS C SDKKinesis、Firehose、STS、EC2 客户端构建时需要确保相关依赖可用osquery 未使用 AWS SDK 默认的 libcurl HTTP 客户端而是通过自定义的OsqueryHttpClientaws_util.cpp复用 osquery 自身的 HTTP 客户端发起请求凭证安全除非在隔离的测试环境不建议把aws_access_key_id/aws_secret_access_key明文写入配置文件更推荐通过环境变量、profile 文件或 IAM 角色配合aws_sts_arn_role/ EC2 实例元数据提供凭证区域校验aws_region及各服务级区域标志的值必须是源码白名单中的合法区域名如us-east-1、eu-west-1等否则初始化会报错1MB 单条记录上限单条日志超过 1MB 时既不会被 Kinesis 服务接受也会在插件组批阶段被主动丢弃日志延迟日志实际发送受aws_kinesis_period/aws_firehose_period默认 10 秒控制因此端到端日志延迟至少为一个刷新周期规划时需考虑这一点。通过以上配置与对底层机制的理解你可以在不引入额外转发组件的前提下让 osquery 的遥测数据直接汇入 AWS 数据管道并将故障排查点收敛在插件自身的批量发送与重试逻辑上。赞分享观测代理网络安全【免费下载链接】osquerySQL powered operating system instrumentation, monitoring, and analytics.项目地址https://gitcode.com/gh_mirrors/os/osquery点击查看免费下载相关推荐osquery 日志体系完全指南logger 插件、调度结果格式与集中式日志输出osquery 日志体系完全指南logger 插件、调度结果格式与集中式日志输出 osquery 守护进程osqueryd默认通过 filesystem观测代理网络安全终极指南如何实现text-generation-inference负载均衡与分布式LLM服务架构终极指南如何实现text generation inference负载均衡与分布式LLM服务架构 text generation inference是一个专为观测代理网络安全Telegraf win_eventlog 插件详解采集 Windows 事件日志的完整配置与源码原理Telegraf win_eventlog 插件详解采集 Windows 事件日志的完整配置与源码原理 本文基于 Telegraf 仓库中 win_event可观测性指标监控运维上一篇AB3DMOT数据预处理KITTI到nuScenes格式转换完全指南下一篇3分钟解决容器网络故障nerdctl与CNI插件重启全攻略创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考