Security copilot

Overview

The security copilot is an automated advisor that continuously analyzes your vault’s security posture, identifies weaknesses, and produces a prioritized action plan. It combines the posture engine’s credential-level analysis with behavioral context from the anomaly detector to generate a narrative remediation roadmap accessible from the admin dashboard. The copilot does not make changes to your vault. It observes, scores, and recommends. All remediation actions require explicit user confirmation.

How the posture engine works

The posture engine (computeSecurityPosture()) examines every credential in your vault and produces a numeric score from 0 to 100 along with a list of typed nudges. Each nudge represents a specific security finding tied to a credential or account setting.

Scoring model

The posture score starts at 100 and applies penalties based on the proportion of credentials affected by each risk category:

Factor	Penalty calculation	Max impact
Weak passwords	`(weakCount / total) * 25`	-25 points
No 2FA on credentials	`(noMfaCount / total) * 15`	-15 points
Stale credentials	`(staleCount / total) * 15`	-15 points
Breached (unresolved)	`breachedCount * 10`	Unbounded
No account-level 2FA	Flat penalty	-15 points
Passkey adoption	Bonus: `(passkeyCount / total) * 10`	+10 points

The final score is clamped to the range 0-100.

Nudge types

Each finding is classified into one of seven nudge types, each with a priority level that determines its position in the copilot plan:

Nudge type	Priority	Trigger
`weak_password`	Critical	Password strength rated weak, very_weak, poor, or critical
`breached_unresolved`	Critical	Credential appears in breach database and has not been rotated
`no_2fa_account`	Critical	PassAgent account has 2FA disabled
`no_totp`	High	Individual credential has no TOTP or passkey
`stale_account`	Medium/High	Password not rotated in 365+ days (High if 730+)
`passkey_available`	Medium	Site supports passkeys but account has not enrolled
`reused_indicator`	Medium	Password reuse detected across credentials

Passkey eligibility is checked against a built-in directory of sites that support WebAuthn. The directory maps domains to setup URLs, so the copilot can link directly to the site’s passkey enrollment page.

Copilot plan generation

The buildCopilotPlan() function transforms raw nudges into a structured, actionable plan. It groups related nudges, estimates score impact, and ranks tasks by priority.

Grouping strategy

Individual nudges are grouped by remediation category so the user sees consolidated tasks rather than hundreds of individual findings:

Group key	Task title	Source nudges
`breach_immediate`	Rotate breached credentials first	`breached_unresolved`
`weak_passwords`	Replace weak passwords with generated strong ones	`weak_password`
`account_2fa`	Enable 2FA on your PassAgent account	`no_2fa_account`
`credential_2fa`	Enable 2FA on accounts without MFA	`no_totp`
`passkey_upgrade`	Upgrade passkey-eligible accounts	`passkey_available`
`stale_rotation`	Rotate stale credentials	`stale_account`

Task structure

Each copilot task includes the following fields:

type CopilotTask = {
  id: string                  // e.g. "task-1-breach_immediate"
  title: string               // Human-readable action title
  reason: string              // Why this matters (with counts)
  priority: "critical" | "high" | "medium" | "low"
  estimatedScoreGain: number  // Projected score improvement (2-18)
  effort: "quick" | "medium" | "deep"
  actionLabel: string         // Button label for the dashboard
  actionUrl?: string          // Deep link to the relevant dashboard tab
  sourceNudgeIds: string[]    // IDs of the underlying nudges
}

Effort classification

The copilot estimates the effort required for each task category:

Quick
Medium
Deep

Tasks that can be completed in under a minute. Includes rotating breached passwords and replacing weak passwords using the built-in generator.

Score projection

The copilot calculates a projected score gain for each task:

Each nudge contributes a base gain derived from its priority: critical = 10, high = 6, medium = 3, low = 1
Gains within a group are summed and scaled by a factor of 0.4
The result is clamped to the range 2-18 per task
The plan caps the top 5 tasks and sums their gains against the current score

The plan’s narrative summarizes the projected improvement, for example: “Complete the top 4 actions to raise your score from 62 to about 84. Start with: Rotate breached credentials first.”

API endpoint

The copilot is accessed via a single authenticated endpoint:

Method	Endpoint	Description
`GET`	`/api/security/copilot`	Generate a full copilot plan for the authenticated user

The response combines the posture analysis, copilot plan, behavioral context, and innovation opportunities into a single payload:

{
  "generatedAt": "2026-03-05T12:00:00.000Z",
  "posture": {
    "score": 62,
    "nudges": [ ... ],
    "stats": {
      "totalCredentials": 48,
      "withTotp": 12,
      "withPasskey": 3,
      "passkeyEligible": 8,
      "staleCount": 15,
      "weakCount": 6,
      "breachedUnresolved": 0
    }
  },
  "copilot": {
    "plan": {
      "currentScore": 62,
      "projectedScore": 84,
      "projectedGain": 22,
      "topRisk": "Replace weak passwords with generated strong ones",
      "narrative": "Complete the top 4 actions to raise your score from 62 to about 84...",
      "tasks": [ ... ]
    },
    "behaviorContext": {
      "learningComplete": true,
      "knownDeviceCount": 3,
      "avgActionsPerSession": 12.4
    }
  },
  "innovationOpportunities": [ ... ]
}

Behavioral context

The copilot enriches its response with data from the behavior profile engine. This gives the dashboard visibility into the user’s device footprint and activity patterns:

learningComplete: whether the behavioral model has collected enough data to make confident anomaly judgments
knownDeviceCount: number of recognized device fingerprints
avgActionsPerSession: average number of vault operations per session

Innovation opportunities

The API also returns a list of recommended platform features that can further strengthen the user’s security posture. These are displayed as suggestions in the admin dashboard:

Opportunity	Status	Description
Risk-adaptive step-up auth	Recommended	Apply stronger checks when anomaly confidence is high
Unified security timeline	Recommended	Combine sign-in, device trust, and breach events into one timeline
One-click auto-remediation	Experimental	Execute grouped fixes with explicit user approval and rollback safety

Dashboard integration

The copilot powers several views in the security dashboard:

Security score

The posture score is displayed as a prominent gauge with color coding (red below 50, yellow 50-75, green above 75).

Action plan

The top 5 prioritized tasks are shown with effort badges, score gain estimates, and direct action links.

Credential health

Individual nudges are grouped by type under tabs for password health, MFA coverage, and passkey opportunities.

Posture trend

Historical posture scores are plotted over time to show improvement or regression.

Each task’s actionUrl deep-links to the relevant dashboard tab:

/dashboard/security?tab=password-health for breach, weak password, and stale credential tasks
/dashboard/security?tab=mfa-auth for account and credential 2FA tasks
/dashboard/security?tab=security-posture for passkey upgrade opportunities

The copilot plan is generated on demand with each API call. There is no cached or stale plan. This ensures the dashboard always reflects the current state of your vault.

Security properties

Read-only analysis: the copilot never modifies vault data. All remediation actions are initiated by the user.
Authenticated access: the endpoint requires a valid session via requireAuthUser(). No public access is possible.
No plaintext access: the posture engine queries metadata columns (strength, encryption_version, timestamps) and never decrypts credential payloads.
Fail-safe: if the posture engine or behavior profile encounters an error, the API returns a 500 rather than an incomplete or misleading plan.

Architecture

Operations

Defense

Compliance

Research

Overview

How the posture engine works

Scoring model

Nudge types

Copilot plan generation

Grouping strategy

Task structure

Effort classification

Score projection

API endpoint

Behavioral context

Innovation opportunities

Dashboard integration

Security score

Action plan

Credential health

Posture trend

Security properties

Architecture

Operations

Defense

Compliance

Research

​Overview

​How the posture engine works

​Scoring model

​Nudge types

​Copilot plan generation

​Grouping strategy

​Task structure

​Effort classification

​Score projection

​API endpoint

​Behavioral context

​Innovation opportunities

​Dashboard integration

Security score

Action plan

Credential health

Posture trend

​Security properties

Overview

How the posture engine works

Scoring model

Nudge types

Copilot plan generation

Grouping strategy

Task structure

Effort classification

Score projection

API endpoint

Behavioral context

Innovation opportunities

Dashboard integration

Security properties