Secret management requirements

secret-management-requirements.md

Requirements

Functional requirements

• Able to rotate any secret we manage

• Able to detect duplicates within a key vault

• Able to manage secret relationships

  • dependent secrets

  • secrets duplicated across key vaults

• Able to validate secrets

• Able to audit secret access (creation, deletion, rotation, fetch)

• Able to audit whether secrets in a key vault are managed or unmanaged

• Able to manage secret expiration events

  • Given that many secrets have expiration dates, how do we want to manage these expirations? ie, if a secret is going to expire in 30 days do we..?

    • send expiration email notifications?

    • warning / failure during a validation build?

    • pend a "rotation operation" and wait for approval?

External interface requirements

• None

Nonfunctional requirements

• Documented scenarios and usage

• Security

  • No self managed identity, use Azure IAM

  • No logging of confidential info (no exposing secrets)

  • No GDPR violations

• Performance

  • This tool should not impact the performance of normal service operations (helix-services, arcade services, azure builds, etc), ie, we should not bring down services for a significant amount of time when a secret is rotated.

  • Perf requirements for validating?

  • Perf requirements for rotating?

  • Key vaults throttle, we should not design a system which impacts our throttle limits

Scope

Additional requirements related to scope are defined in the Scope documentation

Able to detect if an unmanaged secret is being used

Is this supposed to mean that we detect when the vault has secrets we don't know about in it?

Able to validate secrets

Does this imply that we will test every secret against the service it accesses somehow?

Able to determine secret expiration dates

I think determine is the wrong verb here. Secrets just have expiration dates. I'm not really sure what this is saying. We need to be able to rotate the automatic ones before the expiration date, and notify about manual ones before they expire so a human can rotate them.

Do we have dependent secrets? ie, if we rotate one, are there other secrets that have to be rotated as a result

Yes we do. The big one is storage keys and sas tokens. If you rotate the storage key all SAS tokens made with it expire IIRC.

Is this supposed to mean that we detect when the vault has secrets we don't know about in it?

Yeah, we need to discuss this further. Not specifically if there are unknown secrets in the vault, but more, from the services perspective, Mark mentioned this as a p0 in the scope meeting the other day. The note I took was "P0: Prevent services from accessing secrets we don't manage (not in our key vault) and / or bad secrets". We need to figure out if this is really a requirement and how to handle it. Good feedback, I need to fix the wording on this one.

Does this imply that we will test every secret against the service it accesses somehow?

I think that would be an admirable goal and we should figure out how close we can get to it.

Secrets just have expiration dates.

Yes, we need to get crisper on the requirement here but it feels very implementation-y. ie, when a secret is going to expire, do we send a notification to someone? Do we just check secret expiration dates during a build and flag any that are near expiration? Do we just automatically cycle them when they expire or are near expiration (probably not).

These are all good questions and I'll update the gist to denote your comments and that we need more follow up.

Prevent services from accessing secrets we don't manage (not in our key vault) and / or bad secrets

I don't think this is feasible in a finite amount of work. Any service can just write code to access key vault and we can't stop that without writing crazy code analysis that isn't worth the cost in my opinion. We can prevent services using our standard configuration system from accessing unmanaged secrets which is way more feasible and worth doing.

These are great. I think we'll need to have some sort of audit trail too. Who changed what when....