Logging Cheat Sheet / 日志技巧清单

Introduction / 介绍

This cheat sheet is focused on providing developers with concentrated guidance on building application logging mechanisms, especially related to security logging.

此技巧清单专注于为开发者提供集中指导，以构建应用程序日志记录机制，特别是与安全日志记录相关的内容。

Many systems enable network device, operating system, web server, mail server and database server logging, but often custom application event logging is missing, disabled or poorly configured. It provides much greater insight than infrastructure logging alone. Web application (e.g. web site or web service) logging is much more than having web server logs enabled (e.g. using Extended Log File Format).

许多系统启用了网络设备、操作系统、Web 服务器、邮件服务器和数据库服务器的日志记录，但通常自定义应用程序事件日志记录缺失、禁用或配置不当。它比仅基础设施日志记录提供了更深入的洞察。Web 应用程序（例如网站或 Web 服务）的日志记录远不止是启用 Web 服务器日志（例如使用扩展日志文件格式）。

Application logging should be consistent within the application, consistent across an organization's application portfolio and use industry standards where relevant, so the logged event data can be consumed, correlated, analyzed and managed by a wide variety of systems.

应用程序日志记录应在应用程序内部保持一致，在整个组织的应用程序组合中保持一致，并在相关的地方使用行业标准，以便日志记录的事件数据可以被各种系统消费、关联、分析和管理。

Purpose / 目的

Application logging should always be included for security events. Application logs are invaluable data for both security and operational use cases.

应用程序日志记录应始终包含安全事件。应用程序日志对于安全和运营用例都极为宝贵。

Operational use cases / 运营用例

• General debugging
  中文：一般调试
• Establishing baselines
  中文：建立基线
• Business process monitoring e.g. sales process abandonment, transactions, connections
  中文：业务流程监控，例如销售流程放弃、交易、连接
• Providing information about problems and unusual conditions
  中文：提供有关问题和异常情况的信息
• Performance monitoring e.g. data load time, page timeouts
  中文：性能监控，例如数据加载时间、页面超时
• Other business-specific requirements
  中文：其他特定业务需求

Security use cases / 安全用例

Application logging might also be used to record other types of events too such as:

应用程序日志也可能用于记录其他类型的事件，例如：

• Anti-automation monitoring
  中文：反自动化监控
• Identifying security incidents
  中文：识别安全事件
• Monitoring policy violations
  中文：监控策略违规
• Assisting non-repudiation controls (note that the trait non-repudiation is hard to achieve for logs because their trustworthiness is often just based on the logging party being audited properly while mechanisms like digital signatures are hard to utilize here)
  中文：协助不可抵赖性控制（请注意，对于日志而言，不可抵赖性特征难以实现，因为它们的可信度通常仅基于日志记录方的审计是否得当，而数字签名等机制在这里难以利用）
• Audit trails e.g. data addition, modification and deletion, data exports
  中文：审计跟踪，例如数据添加、修改和删除，数据导出
• Compliance monitoring
  中文：合规性监控
• Data for subsequent requests for information e.g. data subject access, freedom of information, litigation, police and other regulatory investigations
  中文：后续信息请求的数据，例如数据主体访问、信息公开、诉讼、警察和其他监管调查
• Legally sanctioned interception of data e.g. application-layer wire-tapping
  中文：法律授权的数据拦截，例如应用层线缆窃听
• Contributing additional application-specific data for incident investigation which is lacking in other log sources
  中文：为事件调查贡献其他日志源中缺乏的特定应用程序数据
• Helping defend against vulnerability identification and exploitation through attack detection
  中文：帮助通过攻击检测防御漏洞识别和利用

Process monitoring, audit, and transaction logs/trails etc. are usually collected for different purposes than security event logging, and this often means they should be kept separate.

进程监控、审计和交易日志/轨迹等通常是为了不同于安全事件记录的不同目的而收集的，这通常意味着它们应该分开保存。

The types of events and details collected will tend to be different.

收集的事件类型和细节可能会有所不同。

For example a PCIDSS audit log will contain a chronological record of activities to provide an independently verifiable trail that permits reconstruction, review and examination to determine the original sequence of attributable transactions. It is important not to log too much, or too little.

例如，一个PCIDSS审计日志将包含一系列活动的按时间顺序记录，以提供一个可独立验证的轨迹，允许重建、审查和检查以确定可追溯的交易原始顺序。不要记录过多或过少是很重要的。

Use knowledge of the intended purposes to guide what, when and how much. The remainder of this cheat sheet primarily discusses security event logging.

使用对预期目的的了解来指导记录什么、何时以及记录多少。本速查表的其余部分主要讨论安全事件记录。

Design, implementation, and testing / 设计、实施和测试

Event data sources / 事件数据源

The application itself has access to a wide range of information events that should be used to generate log entries. Thus, the primary event data source is the application code itself.

应用程序本身可以访问广泛的信息事件，这些事件应用于生成日志条目。因此，主要的事件数据源是应用程序代码本身。

The application has the most information about the user (e.g. identity, roles, permissions) and the context of the event (target, action, outcomes), and often this data is not available to either infrastructure devices, or even closely-related applications.

应用程序拥有关于用户（例如身份、角色、权限）和事件上下文（目标、动作、结果）的最全面信息，并且通常这些数据对基础设施设备甚至紧密相关的应用程序都是不可用的。

Other sources of information about application usage that could also be considered are:

以下是一些关于应用程序使用情况的信息来源，也可以考虑：

• Client software e.g. actions on desktop software and mobile devices in local logs or using messaging technologies, JavaScript exception handler via AJAX, web browser such as using Content Security Policy (CSP) reporting mechanism
  中文：客户端软件，例如桌面软件和移动设备上的本地日志中的操作，或使用消息技术，通过AJAX的JavaScript异常处理器，使用内容安全策略（CSP）报告机制的网络浏览器
• Embedded instrumentation code
  中文：嵌入式仪器代码
• Network firewalls
  中文：网络防火墙
• Network and host intrusion detection systems (NIDS and HIDS)
  中文：网络和主机入侵检测系统（NIDS和HIDS）
• Closely-related applications e.g. filters built into web server software, web server URL redirects/rewrites to scripted custom error pages and handlers
  中文：与相关应用程序紧密相关，例如嵌入到Web服务器软件中的过滤器，Web服务器URL重定向/重写到脚本自定义错误页面和处理程序。
• Application firewalls e.g. filters, guards, XML gateways, database firewalls, web application firewalls (WAFs)
  中文：应用程序防火墙，例如过滤器、守卫、XML网关、数据库防火墙、Web应用程序防火墙（WAF）
• Database applications e.g. automatic audit trails, trigger-based actions
  中文：数据库应用程序，例如自动审计跟踪、基于触发器的操作
• Reputation monitoring services e.g. uptime or malware monitoring
  中文：声誉监控服务，例如可用性或恶意软件监控
• Other applications e.g. fraud monitoring, CRM
  中文：其他应用，例如欺诈监控、CRM
• Operating system e.g. mobile platform
  中文：操作系统，例如移动平台

The degree of confidence in the event information has to be considered when including event data from systems in a different trust zone. Data may be missing, modified, forged, replayed and could be malicious – it must always be treated as untrusted data.

在包含来自不同信任区域的系统的事件数据时，必须考虑对事件信息的信心程度。数据可能缺失、修改、伪造、重放，可能是恶意的 - 必须始终将其视为不受信任的数据。

Consider how the source can be verified, and how integrity and non-repudiation can be enforced.

考虑如何验证源，以及如何强制执行完整性和不可否认性。

Where to record event data / 事件数据的记录位置

Applications commonly write event log data to the file system or a database (SQL or NoSQL). Applications installed on desktops and on mobile devices may use local storage and local databases, as well as sending data to remote storage.

应用程序通常将事件日志数据写入文件系统或数据库（SQL或NoSQL）。安装在桌面和移动设备上的应用程序可能使用本地存储和本地数据库，以及将数据发送到远程存储。

Your selected framework may limit the available choices. All types of applications may send event data to remote systems (instead of or as well as more local storage).

您选择的框架可能限制可用的选择。所有类型的应用程序都可以将事件数据发送到远程系统（而不是或与更本地存储一起）。

This could be a centralized log collection and management system (e.g. SIEM or SEM) or another application elsewhere. Consider whether the application can simply send its event stream, unbuffered, to stdout, for management by the execution environment.

这可能是一个集中式的日志收集和管理系统（例如 SIEM 或 SEM）或另一个位于其他地方的应用程序。考虑该应用程序是否可以简单地将其事件流，未经缓冲，发送到 stdout，由执行环境进行管理。

• When using the file system, it is preferable to use a separate partition than those used by the operating system, other application files and user generated content
  中文：在使用文件系统时，最好使用与操作系统、其他应用程序文件和用户生成内容所使用的分区不同的分区。
  • For file-based logs, apply strict permissions concerning which users can access the directories, and the permissions of files within the directories
    中文：对于基于文件的日志，应严格限制哪些用户可以访问目录，以及目录内文件的权限。
  • In web applications, the logs should not be exposed in web-accessible locations, and if done so, should have restricted access and be configured with a plain text MIME type (not HTML)
    中文：在 Web 应用程序中，日志不应暴露在可访问的 Web 位置，如果这样做，应限制访问并配置为纯文本 MIME 类型（不是 HTML）。
• When using a database, it is preferable to utilize a separate database account that is only used for writing log data and which has very restrictive database, table, function and command permissions
  中文：在使用数据库时，最好使用仅用于写入日志数据的单独数据库账户，并且具有非常严格的数据库、表、函数和命令权限。
• Use a standard event format supported by the receiving system and a secure transport, such as the syslog message format over TLS, to facilitate integration with centralized logging services
  中文：使用接收系统支持的标准化事件格式和安全的传输方式，例如通过TLS的syslog消息格式，以促进与集中式日志服务的集成。

Consider separate files/tables for extended event information such as error stack traces or a record of HTTP request and response headers and bodies.

考虑为扩展事件信息（如错误堆栈跟踪或 HTTP 请求和响应头和体的记录）使用单独的文件/表。

Which events to log / 记录哪些事件

The level and content of security monitoring, alerting, and reporting needs to be set during the requirements and design stage of projects, and should be proportionate to the information security risks. This can then be used to define what should be logged.

安全监控、警报和报告的级别和内容需要在项目的需求和设计阶段设置，并且应与信息安全风险成比例。这可以用来定义应该记录什么内容。

There is no one size fits all solution, and a blind checklist approach can lead to unnecessary "alarm fog" that means real problems go undetected.

Where possible, always log:

• Input validation failures e.g. protocol violations, unacceptable encodings, invalid parameter names and values
  • Log failures to validate a value against a discrete and finite list of valid values (e.g. a country from a dropdown), such as input_validation_fail[:field,userid]. Treat these as suspicious events, not proof of an attack: unexpected input can also result from misuse or client defects. Evaluate severity and alerting using repetition, correlation, and request context.
    中文：记录失败日志以验证值是否与离散且有限的合法值列表（例如下拉列表中的国家）匹配，例如input_validation_fail[:field,userid]。将这些事件视为可疑事件，而不是攻击的证据：意外的输入也可能来自误用或客户端缺陷。使用重复、关联和请求上下文评估严重性和警报。
• Output validation failures e.g. database record set mismatch, invalid data encoding
• Authentication successes and failures Failed authentication attempts provide critical early indicators of credential‑based attacks such as brute‑force, credential‑stuffing, and password‑spraying. Monitoring repeated failures for the same account, failures from multiple IP addresses, or rapid bursts of login attempts helps detect account takeover attempts before they succeed. This aligns with the cheat sheet’s guidance that “Authentication successes and failures” must always be logged, as these events are essential for identifying security incidents and supporting incident investigation. Refer to OWASP ASVS 7.1.1 for authentication failure logging requirements.
  中文：身份验证成功和失败失败的身份验证尝试提供了基于凭证攻击（如暴力破解、凭证填充和密码喷射）的关键早期指标。监控同一账户的重复失败、来自多个IP地址的失败或登录尝试的快速爆发，有助于在成功之前检测到账户接管尝试。这与备忘单的指导原则一致，即“身份验证成功和失败”必须始终记录，因为这些事件对于识别安全事件和支持事件调查至关重要。请参阅OWASP ASVS 7.1.1以获取身份验证失败记录要求。
• Authorization (access control) failures
• Session management failures e.g. cookie session identification value modification or suspicious JWT validation failures
• Application errors and system events e.g. syntax and runtime errors, connectivity problems, performance issues, third party service error messages, file system errors, file upload virus detection, configuration changes
  中文：应用程序错误和系统事件，例如语法和运行时错误、连接问题、性能问题、第三方服务错误消息、文件系统错误、文件上传病毒检测、配置更改
• Application and related systems start-ups and shut-downs, and logging initialization (starting, stopping or pausing)
  中文：应用程序和相关系统的启动和关闭，以及日志初始化（启动、停止或暂停）
• Use of higher-risk functionality including:
  中文：使用高风险功能包括：
  • User administration actions such as addition or deletion of users, changes to privileges, assigning users to tokens, adding or deleting tokens
    中文：用户管理操作，如添加或删除用户、更改权限、将用户分配给令牌、添加或删除令牌
  • Use of systems administrative privileges or access by application administrators including all actions by those users
    中文：使用系统管理权限或应用程序管理员访问，包括那些用户的所有操作
  • Use of default or shared accounts or a "break-glass" account.
    中文：使用默认或共享账户或“破窗”账户
  • Access to sensitive data such as payment cardholder data,
    中文：访问敏感数据，如支付卡持卡人数据
  • Encryption activities such as use or rotation of cryptographic keys
    中文：加密活动，如使用或轮换加密密钥
  • Creation and deletion of system-level objects
    中文：系统级对象的创建和删除
  • Data import and export including screen-based reports
    中文：数据导入和导出，包括基于屏幕的报告
  • Submission and processing of user-generated content - especially file uploads
    中文：用户生成内容的提交和处理 - 尤其是文件上传
  • Deserialization failures
    中文：反序列化失败
  • Network connections and associated failures such as backend TLS failures (including certificate validation failures), or requests with an unexpected HTTP verb
    中文：网络连接及其相关故障，如后端TLS故障（包括证书验证失败），或使用意外HTTP动词的请求
• Legal and other opt-ins e.g. permissions for mobile phone capabilities, terms of use, terms & conditions, personal data usage consent, permission to receive marketing communications
  中文：法律和其他同意事项，例如：移动设备功能的权限、使用条款、条款和条件、个人数据使用同意、接收营销通信的权限
• Suspicious business logic activities such as:
  中文：可疑的业务逻辑活动，例如：
  • Attempts to perform a set actions out of order/bypass flow control
    中文：尝试以错误的顺序/绕过流程控制执行一组操作
  • Actions which don't make sense in the business context
    中文：在业务环境中没有意义的操作
  • Attempts to exceed limitations for particular actions
    中文：尝试超出特定操作的限制

Optionally consider if the following events can be logged and whether it is desirable information:

可选地考虑以下事件是否可以记录，以及是否是所需的信息：

• Sequencing failure
  中文：序列化失败
• Excessive use
  中文：过度使用
• Data changes
  中文：数据变更
• Fraud and other criminal activities
  中文：欺诈和其他犯罪活动
• Suspicious, unacceptable, or unexpected behavior
  中文：可疑、不可接受或意外的行为
• Modifications to configuration
  中文：配置修改
• Application code file and/or memory changes
  中文：应用程序代码文件和/或内存更改

Event attributes

Each log entry needs to include sufficient information for the intended subsequent monitoring and analysis. It could be full content data, but is more likely to be an extract or just summary properties.

The application logs must record "when, where, who and what" for each event.

The properties for these will be different depending on the architecture, class of application and host system/device, but often include the following:

• When
  • Log date and time (international format)
  • Event date and time - the event timestamp may be different to the time of logging e.g. server logging where the client application is hosted on remote device that is only periodically or intermittently online
  • Interaction identifier Note A
• Where
  中文：位置
  • Application identifier e.g. name and version
    中文：应用标识符，例如名称和版本
  • Application address e.g. cluster/hostname or server IPv4 or IPv6 address and port number, workstation identity, local device identifier
    中文：应用程序地址，例如集群/主机名或服务器IPv4或IPv6地址及端口号、工作站标识、本地设备标识
  • Service e.g. name and protocol
    中文：服务，例如名称和协议
  • Geolocation
    中文：地理位置
  • Window/form/page e.g. entry point URL and HTTP method for a web application, dialogue box name
    中文：窗口/表单/页面，例如Web应用程序的入口点URL和HTTP方法、对话框名称
  • Code location e.g. script name, module name
    中文：代码位置，例如脚本名称、模块名称
• Who (human or machine user)
  中文：谁（人类或机器用户）
  • Source address e.g. user's device/machine identifier, user's IP address, cell/RF tower ID, mobile telephone number
    中文：源地址，例如用户设备/机器标识、用户IP地址、蜂窝/RF塔ID、移动电话号码
  • User identity (if authenticated or otherwise known) e.g. user database table primary key-value, username, license number
    中文：用户身份（如果已认证或已知）例如用户数据库表主键值、用户名、许可证号
• What
  中文：什么
  • Type of event Note B
    中文：事件类型注意B
  • Severity of event Note B e.g. {0=emergency, 1=alert, ..., 7=debug}, {fatal, error, warning, info, debug, trace}
    中文：事件Note B的严重程度，例如 {0=紧急, 1=警报, ..., 7=调试}, {致命, 错误, 警告, 信息, 调试, 跟踪}
  • Security relevant event flag (if the logs contain non-security event data too)
    中文：安全相关事件标志（如果日志包含非安全事件数据）
  • Description
    中文：描述

Additionally consider recording:

此外考虑记录：

• Secondary time source (e.g. GPS) event date and time
  中文：次要时间源（例如 GPS）事件日期和时间
• Action - original intended purpose of the request e.g. Log in, Refresh session ID, Log out, Update profile
  中文：操作 - 请求的原始目的，例如 登录，刷新会话 ID，登出，更新个人资料
• Object e.g. the affected component or other object (user account, data resource, file) e.g. URL, Session ID, User account, File
  中文：对象，例如受影响的组件或其他对象（用户账户、数据资源、文件）例如 URL、会话 ID、用户账户、文件
• Result status - whether the ACTION aimed at the OBJECT was successful e.g. Success, Fail, Defer
  中文：结果状态 - ACTION 是否成功针对 OBJECT，例如 成功、失败、延迟
• Reason - why the status above occurred e.g. User not authenticated in database check ..., Incorrect credentials
  中文：原因 - 上文状态发生的原因，例如：数据库中用户未认证检查，凭据错误
• HTTP Status Code (web applications only) - the status code returned to the user (often 200 or 301)
  中文：HTTP 状态码（仅限 Web 应用程序）- 返回给用户的状态码（通常是 200 或 301）
• Request HTTP headers or HTTP User Agent (web applications only)
  中文：请求 HTTP 头部或 HTTP 用户代理（仅限 Web 应用程序）
• User type classification e.g. public, authenticated user, CMS user, search engine, authorized penetration tester, uptime monitor (see "Data to exclude" below)
  中文：用户类型分类，例如：公众用户，认证用户，CMS 用户，搜索引擎，授权渗透测试人员，正常运行时间监控器（见下文“排除数据”部分）
• Analytical confidence in the event detection Note B e.g. low, medium, high or a numeric value
  中文：事件检测的置信度分析 注意 B，例如：低，中，高或数值
• Responses seen by the user and/or taken by the application e.g. status code, custom text messages, session termination, administrator alerts
  中文：用户看到的响应和/或应用程序采取的操作，例如状态码、自定义文本消息、会话终止、管理员警报
• Extended details e.g. stack trace, system error messages, debug information, HTTP request body, HTTP response headers and body
  中文：扩展详情，例如：堆栈跟踪，系统错误消息，调试信息，HTTP 请求体，HTTP 响应头部和体
• Internal classifications e.g. responsibility, compliance references
  中文：内部分类，例如：责任，合规性参考
• External classifications e.g. NIST Security Content Automation Protocol (SCAP), Mitre Common Attack Pattern Enumeration and Classification (CAPEC)
  中文：外部分类，例如：NIST 安全内容自动化协议（SCAP），Mitre 常见攻击模式枚举和分类（CAPEC）

For more information on these, see the "other" related articles listed at the end, especially the comprehensive article by Anton Chuvakin and Gunnar Peterson.

Note A: The "Interaction identifier" is a method of linking all (relevant) events for a single user interaction (e.g. desktop application form submission, web page request, mobile app button click, web service call). The application knows all these events relate to the same interaction, and this should be recorded instead of losing the information and forcing subsequent correlation techniques to re-construct the separate events. For example, a single SOAP request may have multiple input validation failures and they may span a small range of times. As another example, an output validation failure may occur much later than the input submission for a long-running "saga request" submitted by the application to a database server.

Note B: Each organization should ensure it has a consistent, and documented, approach to classification of events (type, confidence, severity), the syntax of descriptions, and field lengths and data types including the format used for dates/times.

Data to exclude

Never log data unless it is legally sanctioned. For example, intercepting some communications, monitoring employees, and collecting some data without consent may all be illegal.

Never exclude any events from "known" users such as other internal systems, "trusted" third parties, search engine robots, uptime/process and other remote monitoring systems, pen testers, auditors. However, you may want to include a classification flag for each of these in the recorded data.

The following should usually not be recorded directly in the logs, but instead should be removed, masked, sanitized, hashed, or encrypted:

• Application source code
• Session identification values (consider replacing with a hashed value if needed to track session specific events)
  中文：会话标识值（如有需要追踪特定会话事件，考虑替换为哈希值）
• Access tokens
  中文：访问令牌
• Sensitive personal data and some forms of personally identifiable information (PII) e.g. health, government identifiers, vulnerable people
  中文：敏感个人信息和某些形式的个人身份信息（PII），例如健康信息、政府标识、易受伤害人群信息
• Authentication passwords
  中文：认证密码
• Database connection strings
  中文：数据库连接字符串
• Encryption keys and other primary secrets
  中文：加密密钥和其他主要机密
• Bank account or payment card holder data
  中文：银行账户或支付卡持卡人数据
• Data of a higher security classification than the logging system is allowed to store
  中文：高于日志系统存储权限的安全分类数据
• Commercially-sensitive information
  中文：商业敏感信息
• Information it is illegal to collect in the relevant jurisdictions
  中文：在相关司法管辖区非法收集的信息
• Information a user has opted out of collection, or not consented to e.g. use of do not track, or where consent to collect has expired
  中文：用户已选择退出收集或未同意收集，例如使用“不要跟踪”或收集同意已过期的情况

Sometimes the following data can also exist, and while useful for subsequent investigation, it may also need to be treated in some special manner before the event is recorded:

有时以下数据也可能存在，尽管对于后续调查有用，但在事件记录之前可能需要以某种特殊方式处理：

• File paths
  中文：文件路径
• Database connection strings
  中文：数据库连接字符串
• Internal network names and addresses
  中文：内部网络名称和地址
• Non sensitive personal data (e.g. personal names, telephone numbers, email addresses)
  中文：非敏感个人数据（例如个人姓名、电话号码、电子邮件地址）

Consider using personal data de-identification techniques such as deletion, scrambling or pseudonymization of direct and indirect identifiers where the individual's identity is not required, or the risk is considered too great.

考虑使用个人数据去标识化技术，如删除、打乱或对直接和间接标识符进行匿名化，当个人身份不是必需的或风险被认为过大时。

In some systems, sanitization can be undertaken post log collection, and prior to log display.

在某些系统中，可以在收集日志之后、显示日志之前进行清理工作。

Customizable logging / 可定制日志记录

It may be desirable to be able to alter the level of logging (type of events based on severity or threat level, amount of detail recorded). If this is implemented, ensure that:

可能需要能够更改日志级别（基于严重性或威胁级别的事件类型，记录的详细程度）。如果实施此功能，请确保以下内容：

• The default level must provide sufficient detail for business needs
  中文：默认级别必须提供满足业务需求足够详细的记录
• It should not be possible to completely deactivate application logging or logging of events that are necessary for compliance requirements
  中文：不应可能完全禁用应用程序日志记录或记录符合性要求必要的事件的日志记录
• Alterations to the level/extent of logging must be intrinsic to the application (e.g. undertaken automatically by the application based on an approved algorithm) or follow change management processes (e.g. changes to configuration data, modification of source code)
  中文：对日志记录级别/程度的更改必须内置于应用程序中（例如，根据批准的算法自动执行）或遵循变更管理流程（例如，配置数据更改、源代码修改）
• The logging level must be verified periodically
  中文：必须定期验证日志级别

Event collection / 事件收集

If your development framework supports suitable logging mechanisms, use or build upon that. Otherwise, implement an application-wide log handler which can be called from other modules/components.

如果您的开发框架支持合适的日志记录机制，请使用或在此基础上构建。否则，实现一个应用程序范围内的日志处理程序，该程序可以从其他模块/组件中调用。

Document the interface referencing the organization-specific event classification and description syntax requirements.

记录接口时，需参照组织特定的事件分类和描述语法要求。

If possible create this log handler as a standard module that can be thoroughly tested, deployed in multiple applications, and added to a list of approved and recommended modules.

如果可能，创建这个日志处理器作为标准模块，以便进行全面测试、在多个应用程序中部署，并添加到已批准和推荐模块的列表中。

• Validate event data from other trust zones before logging it. If a field is malformed, omit or safely replace that field and record the validation failure with bounded, safe context; do not discard the entire security event. This preserves evidence while following OWASP guidance to log validation failures and encode log data safely
  中文：在记录之前验证来自其他信任区域的事件数据。如果字段格式不正确，则省略或安全地替换该字段，并使用有限、安全的环境记录验证失败；不要丢弃整个安全事件。这既保留了证据，又遵循了OWASP关于记录验证失败和安全编码日志数据的指南
• Perform sanitization on all event data to prevent log injection attacks e.g. carriage return (CR), line feed (LF) and delimiter characters (and optionally to remove sensitive data)
  中文：对所有事件数据进行清理，以防止日志注入攻击，例如回车（CR）、换行（LF）和分隔符字符（可选：移除敏感数据）
• Encode data correctly for the output (logged) format
  中文：正确编码数据以适应输出（日志）格式
• If writing to databases, read, understand, and apply the SQL injection cheat sheet
  中文：如果写入数据库，请阅读、理解并应用SQL注入攻击技巧表
• Ensure failures in the logging processes/systems do not prevent the application from otherwise running or allow information leakage
  中文：确保日志记录过程/系统中的故障不会阻止应用程序正常运行或允许信息泄露
• Synchronize time across all servers and devices Note C
  中文：同步所有服务器和设备的时间 注意C

Note C: This is not always possible where the application is running on a device under some other party's control (e.g. on an individual's mobile phone, on a remote customer's workstation which is on another corporate network). In these cases, attempt to measure the time offset, or record a confidence level in the event timestamp.

注意C： 在应用程序运行在其他方控制下的设备（例如，个人的手机、位于另一个企业网络的远程客户工作站）的情况下，这并不总是可能的。在这些情况下，尝试测量时间偏移量，或在事件时间戳中记录置信度水平。

Where possible, record data in a standard format, or at least ensure it can be exported/broadcast using an industry-standard format.

尽可能以标准格式记录数据，或者至少确保可以使用行业标准格式导出/广播。

In some cases, events may be relayed or collected together in intermediate points. In the latter some data may be aggregated or summarized before forwarding on to a central repository and analysis system.

在某些情况下，事件可能在中间节点被中继或收集。在后一种情况下，某些数据可能在转发到中央存储库和分析系统之前被聚合或汇总。

Verification / 验证

Logging functionality and systems must be included in code review, application testing and security verification processes:

日志功能和安全系统必须包含在代码审查、应用程序测试和安全验证过程中：

• Ensure the logging is working correctly and as specified
  中文：确保日志功能按指定方式正确工作
• Check that events are being classified consistently and the field names, types and lengths are correctly defined to an agreed standard
  中文：检查事件是否被一致分类，字段名称、类型和长度是否正确定义为约定标准
• Ensure logging is implemented and enabled during application security, fuzz, penetration, and performance testing
  中文：确保在应用程序安全、模糊测试、渗透测试和性能测试期间实施和启用日志记录
• Test the mechanisms are not susceptible to injection attacks
  中文：测试机制是否不易受到注入攻击
• Ensure there are no unwanted side-effects when logging occurs
  中文：确保日志记录时没有不希望出现的副作用
• Check the effect on the logging mechanisms when external network connectivity is lost (if this is usually required)
  中文：检查外部网络连接丢失时日志机制的影响（如果通常需要的话）
• Ensure logging cannot be used to deplete system resources, for example by filling up disk space or exceeding database transaction log space, leading to denial of service
  中文：确保日志记录不会导致系统资源耗尽，例如通过填满磁盘空间或超出数据库事务日志空间，从而导致拒绝服务（DoS）
• Test the effect on the application of logging failures such as simulated database connectivity loss, lack of file system space, missing write permissions to the file system, and runtime errors in the logging module itself
  中文：测试日志失败对应用程序的影响，例如模拟数据库连接丢失、文件系统空间不足、缺少对文件系统的写权限以及日志模块本身的运行时错误
• Verify access controls on the event log data
  中文：验证事件日志数据的访问控制
• If log data is utilized in any action against users (e.g. blocking access, account lock-out), ensure this cannot be used to cause denial of service (DoS) of other users
  中文：如果日志数据被用于针对用户的任何操作（例如阻止访问、账户锁定），确保这不会导致对其他用户的拒绝服务（DoS）

Network architecture / 网络架构

As an example, the diagram below shows a service that provides business functionality to customers. We recommend creating a centralized system for collecting logs. There may be many such services, but all of them must securely collect logs in a centralized system.

例如，下面的图示显示了一个向客户提供业务功能的服务。我们建议创建一个集中式系统来收集日志。可能有许多这样的服务，但所有这些服务都必须在集中式系统中安全地收集日志。

Applications of this business service are located in network segments:

此业务服务的应用位于以下网络段：

• FRONTEND 1 aka DMZ (UI)
• MIDDLEWARE 1 (business application - service core)
  中文：中间件 1（业务应用 - 服务核心）
• BACKEND 1 (service database)
  中文：后端 1（服务数据库）

The service responsible for collecting IT events, including security events, is located in the following segments:

负责收集 IT 事件（包括安全事件）的服务位于以下部分：

• BACKEND 2 (log storage)
  中文：后端 2（日志存储）
• MIDDLEWARE 3 - 2 applications:
  中文：中间件 3 - 2 个应用：
  • log loader application that download log from storage, pre-processes, and transfer to UI
    中文：日志加载应用，从存储中下载日志，预处理，并传输到 UI
  • log collector that accepts logs from business applications, other infrastructure, cloud applications and saves in log storage
    中文：日志收集器，接受来自业务应用、其他基础设施、云应用的日志，并存储在日志存储中
• FRONTEND 2 (UI for viewing business service event logs)
  中文：前端 2（查看业务服务事件日志的 UI）
• FRONTEND 3 (applications that receive logs from cloud applications and transfer logs to log collector)
  中文：前端3（从云应用接收日志并将日志传输到日志收集器的应用程序）
  • It is allowed to combine the functionality of two applications in one
    中文：允许将两个应用程序的功能合并为一个

For example, all external requests from users go through the API management service, see application in MIDDLEWARE 2 segment.

例如，所有来自用户的对外请求都通过API管理服务进行，请参见中间件2段的应用程序。

As you can see in the image above, at the network level, the processes of saving and downloading logs require opening different network accesses (ports), arrows are highlighted in different colors. Also, saving and downloading are performed by different applications.

如图所示，在网络层面，保存和下载日志的过程需要打开不同的网络访问（端口），箭头以不同的颜色突出显示。保存和下载由不同的应用程序执行。

Full network segmentation cheat sheet by sergiomarotco: link

由sergiomarotco提供的完整网络分段速查表：链接

Deployment and operation / 部署和运维

Release / 发布

• Provide security configuration information by adding details about the logging mechanisms to release documentation
  中文：通过在发布文档中添加关于日志机制的详细信息来提供安全配置信息
• Brief the application/process owner about the application logging mechanisms
  中文：向应用程序/流程所有者简要介绍应用程序的日志记录机制
• Ensure the outputs of the monitoring (see below) are integrated with incident response processes
  中文：确保监控输出的结果（见下文）与事件响应流程集成

Operation / 操作

Enable processes to detect whether logging has stopped, and to identify tampering or unauthorized access and deletion (see protection below).

启用流程以检测日志是否停止，以及识别篡改或未经授权的访问和删除（见下文保护措施）。

Protection / 保护

The logging mechanisms and collected event data must be protected from mis-use such as tampering in transit, and unauthorized access, modification and deletion once stored. Logs may contain personal and other sensitive information, or the data may contain information regarding the application's code and logic.

日志机制和收集的事件数据必须受到保护，防止在传输过程中的篡改，以及存储后的未经授权的访问、修改和删除。日志可能包含个人和其他敏感信息，或者数据可能包含关于应用程序代码和逻辑的信息。

In addition, the collected information in the logs may itself have business value (to competitors, gossip-mongers, journalists and activists) such as allowing the estimate of revenues, or providing performance information about employees.

此外，日志中收集的信息本身可能具有商业价值（对竞争对手、八卦者、记者和活动家），例如允许估计收入，或提供关于员工绩效的信息。

This data may be held on end devices, at intermediate points, in centralized repositories and in archives and backups.

这些数据可能存储在终端设备上、中间点、集中存储库、存档和备份中。

Consider whether parts of the data may need to be excluded, masked, sanitized, hashed, or encrypted during examination or extraction.

考虑是否需要排除、遮蔽、清理、哈希或加密数据的一部分，在审查或提取过程中。

At rest:

静态存储:

• Build in tamper detection so you know if a record has been modified or deleted
  中文：内置篡改检测功能，以便您知道记录是否已被修改或删除
• Store or copy log data to read-only media as soon as possible
  中文：尽可能快地将日志数据存储或复制到只读介质上
• All access to the logs must be recorded and monitored (and may need prior approval)
  中文：所有对日志的访问都必须记录和监控（可能需要事先批准）
• The privileges to read log data should be restricted and reviewed periodically
  中文：应限制读取日志数据的权限，并定期进行审查

In transit:

传输中:

• If log data is sent over untrusted networks (e.g. for collection, for dispatch elsewhere, for analysis, for reporting), use a secure transmission protocol
  中文：如果日志数据通过不受信任的网络（例如，用于收集、发送到其他地方、分析、报告）传输，请使用安全的传输协议
• Consider whether the origin of the event data needs to be verified
  中文：考虑是否需要验证事件数据的来源
• Perform due diligence checks (regulatory and security) before sending event data to third parties
  中文：在进行事件数据发送给第三方之前，执行尽职调查（监管和安全）检查

See NIST SP 800-92 Guide to Computer Security Log Management for more guidance.

参见NIST SP 800-92计算机安全日志管理指南以获取更多指导

Monitoring of events / 事件监控

The logged event data needs to be available to review and there are processes in place for appropriate monitoring, alerting, and reporting:

记录的事件数据需要可供审查，并且有适当的监控、警报和报告流程：

• Incorporate the application logging into any existing log management systems/infrastructure e.g. centralized logging and analysis systems
  中文：将应用程序的日志记录集成到任何现有的日志管理系统/基础设施中，例如集中式日志和分析系统
• Ensure event information is available to appropriate teams
  中文：确保事件信息可供相关团队访问
• Enable alerting and signal the responsible teams about more serious events immediately
  中文：启用警报并立即通知负责团队关于更严重事件的信息
• Share relevant event information with other detection systems, to related organizations and centralized intelligence gathering/sharing systems
  中文：与其他检测系统、相关组织和集中式情报收集/共享系统共享相关事件信息

Disposal of logs / 日志销毁

Log data, temporary debug logs, and backups/copies/extractions, must not be destroyed before the duration of the required data retention period, and must not be kept beyond this time.

日志数据、临时调试日志以及备份/副本/提取，在所需数据保留期限之前不得销毁，并且不得在此之后保留

Legal, regulatory and contractual obligations may impact on these periods.

法律、法规和合同义务可能影响这些期限。

Attacks on Logs / 对日志的攻击

Because of their usefulness as a defense, logs may be a target of attacks. See also OWASP Log Injection and CWE-117.

由于日志在防御中的有用性，它们可能成为攻击的目标。另见 OWASP 日志注入 和 CWE-117。

Log Injection / 日志注入

Log Injection) （日志注入） occurs when an application includes untrusted data in an application log message (e.g., an attacker can cause an additional log entry that looks like it came from a completely different user, if they can inject CRLF characters in the untrusted data). More information about this attack is available on the OWASP Log Injection page.

To prevent an attacker from writing malicious content into the application log, apply defenses such as:

为了防止攻击者将恶意内容写入应用程序日志，应用以下防御措施：

• Do not use unstructured text log formats. In many logging frameworks, unstructured text log formats are susceptible to log entry injection through Carriage Return (CR) or Line Feed (LF) characters (see CWE-93). Some logging frameworks do not consider log injections through CRLF in unstructured logs to be a vulnerability (which means that this will not be fixed).
  中文：不要使用非结构化文本日志格式。在许多日志框架中，非结构化文本日志格式容易受到通过回车（CR）或换行（LF）字符进行的日志条目注入的影响（参见 CWE-93）。一些日志框架不认为非结构化日志中的CRLF注入是一个漏洞（这意味着这不会被修复）
• Instead, use structured log formats, such as JSON.
  中文：相反，使用结构化日志格式，例如 JSON。
• Limit the size of the user input value used to create the log message.
  中文：限制用于创建日志消息的用户输入值的长度。

Log Injection in Java / Java 中的日志注入

In Java, do not use string concatenation to build log messages:

在Java中，不要使用字符串连接来构建日志消息：

// BAD: placeholders in `username` can change which values fill the template.
logger.warn("Failure for user " + username + " and role {}.", role, ex);

// OK
logger.warn("Failure for user {} and role {}.", username, role, ex);

Keep message templates constant with Log4j and SLF4J, including when using Logback. Parameterized logging alone does not prevent CR/LF log injection; use a structured encoder that escapes values correctly.

使用Log4j和SLF4J时，保持消息模板不变，包括使用Logback。参数化日志本身不能防止CR/LF日志注入；请使用能够正确转义值的结构化编码器。

In Log4j, the maxStringLength parameter of JsonTemplateLayout truncates each string value before appending a suffix; it does not cap encoded bytes or total event size:

在Log4j中，JsonTemplateLayout的maxStringLength参数在追加后缀之前截断每个字符串值；它不会限制编码的字节或事件总大小：

<JsonTemplateLayout maxStringLength="500" />

References:

参考资料：

• Log4j API Best Practices) （Log4j API最佳实践）.

Confidentiality / 机密性

Who should be able to read what? A confidentiality attack enables an unauthorized party to access sensitive information stored in logs.

谁应该能够阅读什么？机密性攻击允许未经授权的实体访问存储在日志中的敏感信息。

• Logs contain PII of users. Attackers gather PII, then either release it or use it as a stepping stone for further attacks on those users.
  中文：日志包含用户的PII（个人身份信息）。攻击者收集PII，然后要么发布它，要么将其用作进一步攻击这些用户的跳板。
• Logs contain technical secrets such as passwords. Attackers use it as a stepping stone for deeper attacks.
  中文：日志包含技术机密，如密码。攻击者将其用作更深入攻击的跳板。

Integrity / 完整性

Which information should be modifiable by whom?

哪些信息应该由谁修改？

• An attacker with read access to a log uses it to exfiltrate secrets.
  中文：一个具有读取日志访问权限的攻击者使用它来泄露机密信息。
• An attack leverages logs to connect with exploitable facets of logging platforms, such as sending in a payload over syslog in order to cause an out-of-bounds write.
  中文：攻击利用日志连接到可利用的日志平台方面，例如通过syslog发送有效负载以导致越界写入。

Availability / 可用性

What downtime is acceptable?

可接受的停机时间是多少？

• An attacker floods log files in order to exhaust disk space available for non-logging facets of system functioning. For example, the same disk used for log files might be used for SQL storage of application data.
  中文：攻击者通过填充日志文件来耗尽系统功能非日志方面的磁盘空间。例如，用于日志文件的同一磁盘可能用于应用程序数据的SQL存储。
• An attacker floods log files in order to exhaust disk space available for further logging.
  中文：攻击者通过填充日志文件来耗尽可用于进一步日志记录的磁盘空间。
• An attacker uses one log entry to destroy other log entries.
  中文：攻击者利用一条日志条目来破坏其他日志条目。
• An attacker leverages poor performance of logging code to reduce application performance
  中文：攻击者利用日志代码性能不佳来降低应用程序性能

Accountability / 问责制

Who is responsible for harm?

谁应对损害负责？

• An attacker prevent writes in order to cover their tracks.
  中文：攻击者阻止写入以掩盖其行踪。
• An attacker prevent damages the log in order to cover their tracks.
  中文：攻击者阻止损坏日志以掩盖其行踪。
• An attacker causes the wrong identity to be logged in order to conceal the responsible party.
  中文：攻击者导致错误的身份被记录，以隐藏责任方。

References / 参考

• NIST SP 800-92: Guide to Computer Security Log Management) （NIST SP 800-92：计算机安全日志管理指南）
• RFC 5424: The Syslog Protocol) （RFC 5424：系统日志协议）
• W3C: Extended Log File Format (Working Draft)) （W3C：扩展日志文件格式（工作草案））