# Story 4.14: Marketplace Security Signals Ingestion

## Status: Cancelled

## Priority: Medium

## Estimated Effort: Medium (2-3 days)

## Dependencies

- **Depends on:** Story 4.13 (CI Security Scanning & SBOM Publishing) - Needs security artifacts

## Epic / Series

Part of Epic 4: Enterprise Compliance & Observability / Series 4.x

---

## Cancellation Notice

**Cancelled:** 2026-01-16

**Reason:** Strategic decision to remove marketplace from fapilog core. A plugin marketplace is premature infrastructure for the current ecosystem size. PyPI + entry points provide sufficient discovery and installation. See Story 6.12 for details.

**Alternative:** Security signals (SBOM, vulnerability scans) remain valuable via Story 4.13 and can be published to GitHub releases / PyPI metadata without a custom marketplace.

---

## Original Context / Background

Marketplace users need to quickly assess plugin health and compliance. Displaying security scan summaries (vulnerability counts, scan date) in marketplace listings helps users make informed decisions about which plugins to use.

---

## Original User Story

**As a** marketplace user
**I want** marketplace listings to display security scan summaries (vuln counts, scan date)
**So that** I can quickly assess plugin health and compliance

---

## Scope (In / Out)

### In Scope

- Extend MarketplaceIndexItem with optional `security_summary` field
- Index builder ingests JSON from gh-pages security-artifacts/
- Offline-friendly: builder works without artifacts
- Unit tests for ingestion logic

### Out of Scope

- Generating the security artifacts (covered in Story 4.13)
- Real-time security scanning
- Security remediation workflows

---

## Acceptance Criteria

### AC1: Marketplace Schema Extension

- [ ] `MarketplacePluginIndexItem` includes optional `security_summary` field:
  ```python
  security_summary: Optional[SecuritySummary] = None
  
  class SecuritySummary(BaseModel):
      critical: int = 0
      high: int = 0
      medium: int = 0
      low: int = 0
      last_scanned: Optional[str] = None  # ISO 8601 date
  ```
- [ ] Schema version bumped appropriately
- [ ] Backward compatible (optional field)

### AC2: Artifact Ingestion

- [ ] Index builder optionally reads JSON from `security-artifacts/` directory
- [ ] Ingestion happens via builder parameter (e.g., `security_artifacts_path`)
- [ ] Builder remains offline-friendly (works without artifacts)
- [ ] Missing artifacts don't break the build

### AC3: Testing

- [ ] Unit tests for ingestion logic with fixture JSON
- [ ] Tests cover:
  - [ ] Successful ingestion
  - [ ] Missing artifacts (graceful handling)
  - [ ] Malformed JSON (error handling)
  - [ ] Schema validation

---

## Technical Design / Implementation Notes

### Schema Changes

Location: Marketplace index schema (likely in `docs/` or plugin registry code)

```python
class SecuritySummary(BaseModel):
    """Security scan summary for marketplace display."""
    critical: int = Field(default=0, ge=0)
    high: int = Field(default=0, ge=0)
    medium: int = Field(default=0, ge=0)
    low: int = Field(default=0, ge=0)
    last_scanned: Optional[str] = Field(
        default=None,
        description="ISO 8601 timestamp of last scan"
    )

class MarketplacePluginIndexItem(BaseModel):
    # ... existing fields ...
    security_summary: Optional[SecuritySummary] = None
```

### Artifact Format

Expected JSON structure in `security-artifacts/{plugin-name}.json`:
```json
{
  "critical": 0,
  "high": 2,
  "medium": 5,
  "low": 10,
  "last_scanned": "2025-01-10T12:00:00Z"
}
```

### Builder Integration

- Add optional parameter: `security_artifacts_path: Optional[Path] = None`
- If provided, read artifacts and merge into index items
- If not provided or missing, leave `security_summary` as None

---

## Tasks

### Phase 1: Schema & Data Model
- [ ] Define `SecuritySummary` model
- [ ] Extend `MarketplacePluginIndexItem` with optional field
- [ ] Bump schema version
- [ ] Update type definitions

### Phase 2: Ingestion Logic
- [ ] Add builder parameter for artifacts path
- [ ] Implement artifact reading logic
- [ ] Implement JSON parsing and validation
- [ ] Handle missing/malformed artifacts gracefully

### Phase 3: Testing
- [ ] Create fixture JSON files
- [ ] Write unit tests for ingestion
- [ ] Test error cases
- [ ] Test offline mode (no artifacts)

### Phase 4: Documentation
- [ ] Document artifact format
- [ ] Document builder usage
- [ ] Update marketplace documentation

---

## Tests

### Unit Tests

- [ ] Test successful ingestion with valid JSON
- [ ] Test missing artifacts (should not fail)
- [ ] Test malformed JSON (should handle gracefully)
- [ ] Test schema validation
- [ ] Test offline mode (no artifacts path provided)

### Integration Tests

- [ ] Test full builder workflow with artifacts
- [ ] Test marketplace index generation with security data

---

## Documentation Updates

- [ ] Document security summary schema
- [ ] Document artifact format
- [ ] Document builder usage with artifacts
- [ ] Update marketplace documentation to show security signals

---

## Definition of Done

Story is complete when ALL of the following are true:

### Code Complete
- [ ] All acceptance criteria met and verified
- [ ] All tasks completed
- [ ] Code follows project style guide
- [ ] No linting errors or warnings
- [ ] Type checking passes (mypy strict)

### Quality Assurance
- [ ] Unit tests: >90% coverage of new code
- [ ] Integration tests: all scenarios passing
- [ ] Regression tests: no existing functionality broken
- [ ] Performance tests: no regression vs baseline
- [ ] Manual testing completed (if applicable)

### Documentation
- [ ] User-facing docs updated
- [ ] API reference updated (if applicable)
- [ ] Code examples added/updated
- [ ] CHANGELOG.md updated
- [ ] Inline code documentation complete

### Review & Release
- [ ] Code review approved
- [ ] Documentation reviewed for clarity
- [ ] CI/CD pipeline passing
- [ ] Ready for merge to main branch

### Backwards Compatibility
- [ ] No breaking changes OR breaking changes documented with migration guide
- [ ] Existing tests still pass
- [ ] Deprecation warnings added (if applicable)

---

## Risks / Rollback / Monitoring

### Risks

- **Risk:** Artifact format changes break ingestion
  - **Mitigation:** Version artifact format, validate schema strictly

- **Risk:** Offline builds fail if artifacts required
  - **Mitigation:** Make artifacts optional, builder works without them

### Rollback Plan

- Remove `security_summary` field from schema (backward compatible)
- Builder continues to work without artifacts

---

## Related Documents

- [Story 4.13: CI Security Scanning & SBOM Publishing](./4.13.ci-security-scanning-sbom.md)
- [Story 4.15: Developer Docs for Security Scans](./4.15.developer-docs-security-scans.md)

---

## Change Log

| Date       | Change                    | Author |
| ---------- | ------------------------- | ------ |
| 2025-01-10 | Initial story creation    | System |
