# Story 5.33: Address Audit Report Findings

**Status:** Complete
**Priority:** High
**Estimated Effort:** Small (1 day)
**Depends on:** None

---

## Context / Background

Deep audits of the fapilog library were conducted by multiple AI models (GPT-5.2, Claude Opus 4.5, Gemini-3-Flash, Grok) in January 2026. The reports identified several issues that, after manual verification against the codebase, have been confirmed as valid and actionable.

This story consolidates all verified findings into a single implementation effort to improve security posture, documentation accuracy, and enterprise adoption readiness.

**Audit Reports Location:** `docs/audits/`

---

## Scope (In / Out)

### In Scope

- Security: Bump orjson minimum version to fix CVE-2024-27454
- Security: Add SECURITY.md with vulnerability reporting guidance
- Documentation: Fix Python version badge mismatch (3.8 vs 3.10)
- Documentation: Clarify plugin entry point group naming in architecture docs
- Documentation: Elevate existing `drop_on_full` guidance to be more prominent in README
- Documentation: Update CloudWatch sink comments about conservative size limit
- Governance: Add CODE_OF_CONDUCT.md
- Documentation: Update CONTRIBUTING.md with correct Python version and new file references

### Out of Scope

- Marketplace implementation (tracked separately)
- fapilog-tamper production readiness (already documented as placeholder)
- Single maintainer risk (not addressable via code changes)

---

## Acceptance Criteria

### AC1: orjson Version Bump (Security)

**Description:** Raise orjson minimum version to address CVE-2024-27454.

**Validation:**

- [ ] `pyproject.toml` updated: `orjson>=3.9.15` (was `>=3.9.0`)
- [ ] CI passes with new version constraint
- [ ] No functionality regression

**Evidence:** [CVE-2024-27454](https://nvd.nist.gov/vuln/detail/CVE-2024-27454) - recursion DoS fixed in 3.9.15.

### AC2: SECURITY.md Added

**Description:** Add security policy for vulnerability reporting.

**Validation:**

- [ ] `SECURITY.md` exists in repository root
- [ ] Contains supported versions section
- [ ] Contains vulnerability reporting instructions
- [ ] References responsible disclosure timeline

### AC3: Python Version Badge Fixed

**Description:** README badge matches actual Python version requirement.

**Validation:**

- [ ] `README.md` badge updated from "Python 3.8+" to "Python 3.10+"
- [ ] Badge URL points to correct version
- [ ] Any other 3.8/3.9 references in README updated

**Current State:**

- `README.md:13`: Badge says "Python 3.8+"
- `pyproject.toml:32`: `requires-python = ">=3.10"`

### AC4: Plugin Group Documentation Clarified

**Description:** Architecture docs clearly document the specific entry point groups.

**Validation:**

- [ ] `docs/architecture/high-level-architecture.md` updated
- [ ] Remove/clarify the confusing `group="fapilog.plugins"` reference at line 143
- [ ] Explicitly list all groups: `fapilog.sinks`, `fapilog.enrichers`, `fapilog.redactors`, `fapilog.processors`, `fapilog.filters`
- [ ] Note that legacy `fapilog.plugins` is deprecated

### AC5: Elevate Production Configuration Guidance

**Description:** Make existing `drop_on_full` guidance more prominent in README.

**Current State:**

- `settings.py:628` defaults to `drop_on_full=True`
- README line 299 has a "Reliability hint" buried in docs section
- `docs/user-guide/reliability-defaults.md` has comprehensive guidance
- `production` preset already sets `drop_on_full=False` (`presets.py:29`)

**Validation:**

- [ ] README.md has a prominent callout near Quick Start (not just buried at bottom)
- [ ] Callout recommends using `preset="production"` for durability

**Note:** Existing guidance is adequate; this AC elevates visibility only.

### AC6: CloudWatch Sink Documentation

**Description:** Document that CloudWatch size limit is intentionally conservative.

**Validation:**

- [ ] `src/fapilog/plugins/sinks/contrib/cloudwatch.py` has comment explaining 256KB limit
- [ ] Comment notes AWS now supports 1MB but we use conservative limit for compatibility
- [ ] Optional: Add configuration option to allow larger events

### AC7: CODE_OF_CONDUCT.md Added

**Description:** Add code of conduct for community governance.

**Validation:**

- [ ] `CODE_OF_CONDUCT.md` exists in repository root
- [ ] Uses Contributor Covenant or similar standard
- [ ] References enforcement contact

### AC8: CONTRIBUTING.md Updated

**Description:** Fix outdated information and add references to new governance files.

**Current State:**

- Line 20: Says "Python 3.8 or higher" (should be 3.10)
- Line 29: References `fastapi-logger` repo name
- No reference to SECURITY.md for vulnerability reporting
- No reference to CODE_OF_CONDUCT.md

**Validation:**

- [ ] Python version updated to "3.10 or higher"
- [ ] Repository name corrected to `fapilog`
- [ ] "Reporting Security Issues" section added, referencing SECURITY.md
- [ ] Reference to CODE_OF_CONDUCT.md added in guidelines section

---

## Implementation Notes

### File Changes

```text
pyproject.toml                                  (MODIFIED - orjson version)
README.md                                       (MODIFIED - Python badge, production tip callout)
CONTRIBUTING.md                                 (MODIFIED - Python version, repo name, new file refs)
SECURITY.md                                     (NEW)
CODE_OF_CONDUCT.md                              (NEW)
docs/architecture/high-level-architecture.md    (MODIFIED - plugin groups)
src/fapilog/plugins/sinks/contrib/cloudwatch.py (MODIFIED - size limit comment)
```

### Key Changes

**pyproject.toml (line 42):**

```toml
# Before
"orjson>=3.9.0",

# After
"orjson>=3.9.15",  # CVE-2024-27454 fixed in 3.9.15
```

**README.md badge (line 13):**

```markdown
# Before
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-008080?...

# After
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-008080?...
```

**README.md production callout (new callout after Quick Start, elevating existing guidance):**

```markdown
> **Production Tip:** Use `preset="production"` for log durability - it sets
> `drop_on_full=False` to prevent silent log drops under load. See
> [reliability defaults](docs/user-guide/reliability-defaults.md) for details.
```

**cloudwatch.py constant comment:**

```python
# CloudWatch historically had a 256 KB per-event limit. AWS increased this to
# 1 MB in late 2024, but we keep the conservative limit for broad compatibility.
# Users needing larger events can implement a custom sink with higher limits.
MAX_EVENT_SIZE_BYTES = 256 * 1024  # 256 KB (conservative)
```

---

## Tasks

### Phase 1: Security Fixes

- [ ] Update orjson version in `pyproject.toml` to `>=3.9.15`
- [ ] Create `SECURITY.md` with vulnerability reporting process
- [ ] Verify CI passes with new orjson constraint

### Phase 2: Documentation Fixes

- [ ] Update Python version badge in `README.md`
- [ ] Add prominent production tip callout near Quick Start in `README.md`
- [ ] Update `docs/architecture/high-level-architecture.md` plugin groups
- [ ] Add comment to CloudWatch sink about conservative size limit
- [ ] Update `CONTRIBUTING.md` Python version (3.8 → 3.10)
- [ ] Update `CONTRIBUTING.md` repo name reference
- [ ] Add security reporting and code of conduct references to `CONTRIBUTING.md`

### Phase 3: Governance

- [ ] Create `CODE_OF_CONDUCT.md` (Contributor Covenant 2.1)

### Phase 4: Verification

- [ ] Run full test suite
- [ ] Verify all new files render correctly
- [ ] Check links in SECURITY.md and CODE_OF_CONDUCT.md

---

## Tests

### Manual Verification

- [ ] `pip install orjson>=3.9.15` succeeds
- [ ] No import errors with new orjson version
- [ ] README badge displays correctly on GitHub
- [ ] SECURITY.md renders correctly on GitHub
- [ ] CODE_OF_CONDUCT.md renders correctly on GitHub

### CI Verification

- [ ] All existing tests pass
- [ ] Linting passes
- [ ] Type checking passes

---

## Definition of Done

### Code Complete

- [ ] All acceptance criteria met
- [ ] No linting errors
- [ ] Type checking passes

### Quality Assurance

- [ ] Existing tests pass
- [ ] Manual verification completed

### Documentation

- [ ] SECURITY.md created
- [ ] CODE_OF_CONDUCT.md created
- [ ] README updated (badge + production tip)
- [ ] CONTRIBUTING.md updated (Python version, repo name, new file refs)
- [ ] Architecture docs updated (plugin groups)
- [ ] CloudWatch sink comment added
- [ ] CHANGELOG.md updated

---

## Risks / Rollback

### Risks

1. **Risk:** orjson version bump breaks environments with pinned old versions
   - **Mitigation:** 3.9.15 is from early 2024; most environments already have newer

2. **Risk:** Documentation changes create broken links
   - **Mitigation:** Verify all links before merge

### Rollback Plan

- Revert commit (no data migration required)
- All changes are additive or comment-only

---

## Related Documents

- [Audit Reports](../audits/)
- [CVE-2024-27454](https://nvd.nist.gov/vuln/detail/CVE-2024-27454)
- [Contributor Covenant](https://www.contributor-covenant.org/)

---

## Change Log

| Date       | Change                             | Author |
|------------|------------------------------------|--------|
| 2026-01-16 | Initial draft from audit analysis | Claude |
