adclient

type ADGroups []*Group

type AccountState string

type Client interface {
	Execute(cmd string) (string, error)
	Close() error
}

type Domain struct {
	Forest      string `json:"Forest"`
	NetBIOSName string `json:"NetBIOSName"`
	DNSRoot     string `json:"DNSRoot"`
	Name        string `json:"Name"`

	// DomainSID is the domain's security identifier, in its S-1-5-21-... string
	// form.
	//
	// This is the only name for the domain that is actually stable. The other
	// four are all renameable - a domain rename changes the DNS root, the
	// NetBIOS name and the flat name together - and the SID is assigned when the
	// domain is created and survives every one of them. Anything asking "is this
	// the same directory as the one I saw before" has to ask it of this field.
	DomainSID string `json:"DomainSID"`
}

type GetADGroupArgs struct {
	NamePrefix *string
	MaxCount   *int64
	Cursor     *string

	// Server is the controller a first page is read from. A continuation uses the
	// one its cursor names, so that every page of one listing sees a single
	// replica's view. Empty means discover.
	//
	// It is taken as already validated: it reaches here from the agent's own
	// configuration, where it was checked once, and re-checking it per page would
	// spend exactly the command this field exists to avoid.
	Server string

	// Scope restricts which containers groups are listed from. An empty scope
	// means the whole domain.
	//
	// Deliberately its own scope rather than the one that restricts accounts.
	// Groups conventionally live in a container of their own, so applying the
	// account bases here would list nothing at all in an ordinary domain. The same
	// scope controls membership projection, so the groups offered for policy and
	// the memberships those policies evaluate cannot disagree.
	Scope Scope
}

type GetADUserArgs struct {
	Identity string

	// Server is the domain controller to read from. Empty means whichever one
	// PowerShell picks, which is only safe where the request makes no other
	// read to disagree with.
	Server string
}

type Group struct {
	Name       string `json:"Name"`
	ObjectGUID string `json:"ObjectGUID"`
}

type IneligibleReason string

type ListADUsersArgs struct {
	// Cursor continues an enumeration in progress.
	Cursor *string

	// ProviderState is the watermark from the last completed enumeration. Its
	// absence means a full reconciliation is being asked for.
	ProviderState *string

	// Scope restricts which accounts are eligible.
	Scope Scope

	// GroupScope restricts which direct group memberships this directory stores
	// and enforces. Empty means every group in the account's local domain.
	GroupScope Scope

	// Server is the controller a *new* walk starts against. A walk already in
	// progress, or one resuming above a stored watermark, uses the controller its
	// cursor or state names instead - sequence numbers mean nothing on another
	// one, so that is not a preference to be overridden. Empty means discover.
	//
	// So changing which controller this agent prefers does not move an
	// enumeration that already has a watermark. startOrResumeWalk says so in the
	// log when the two disagree, because the remedy - a full synchronization -
	// is not something an operator would guess at.
	Server string

	// Deadline is the instant the caller stops waiting for the request this page
	// belongs to. The zero time means unbounded.
	//
	// It exists because overrunning it is not a slow answer but a discarded
	// one: the server closes the connection and everything the walk learned goes
	// with it. Rather than risk that, a page stops early and returns a cursor -
	// the protocol already handles a short page, and the cursor carries the
	// window the walk had arrived at.
	//
	// An instant rather than a duration, because a duration is only the right
	// bound if the walk starts counting the moment the caller does. It does not:
	// resolving the scope, the group containers and the pinned controller all
	// happen first, and each of those is a round trip bounded only by
	// commandTimeout. Measured from here, a page could grant itself a deadline
	// minutes past the one the server was actually keeping, spend the whole
	// reserve before its first range, and lose the finished page to a recycled
	// connection. The caller stamps this on arrival so both sides bound the same
	// interval.
	Deadline time.Time
}

type ListADUsersDiagnostics struct {
	Skipped               map[IneligibleReason]int `json:"skipped,omitempty"`
	MissingIdentifiers    int                      `json:"missing_identifiers,omitempty"`
	InvalidTimestamps     int                      `json:"invalid_timestamps,omitempty"`
	UnresolvedMemberships int                      `json:"unresolved_memberships,omitempty"`
	// Separate from UnresolvedMemberships because the two have opposite
	// remedies. An unresolved membership was asked about and not answered, which
	// a re-synchronization commonly fixes on its own; an unclassifiable one was
	// never asked about, because its distinguished name would not parse here.
	// Reported as one number, the second sent an operator to check replication
	// for a fault that only editing the object in AD can clear.
	UnclassifiableMemberships int  `json:"unclassifiable_memberships,omitempty"`
	RecoveredRangeTimeouts    int  `json:"recovered_range_timeouts,omitempty"`
	PreferredDCReported       bool `json:"preferred_dc_reported,omitempty"`
}

type ListADUsersResult struct {
	Users       Users
	Diagnostics ListADUsersDiagnostics

	// NextCursor continues this enumeration. Nil on the final page.
	NextCursor *string

	// NextProviderState is the watermark to remember for next time. Set only on
	// the final page, because only then is the enumeration known to have
	// completed - and set even when the page is empty, since a nil state tells
	// the server to reconcile again.
	NextProviderState *string
	// contains filtered or unexported fields
}

type PasswordArgs struct {
	UserImmutableID string
}

type PasswordPolicy struct {
	MinPasswordLength *int `json:"MinPasswordLength,omitempty"`
}

type PowershellClient struct {
	// contains filtered or unexported fields
}

type PrimaryGroups struct {
	// contains filtered or unexported fields
}

type ProviderState struct {
	V int `json:"v"`

	// DC and Inv identify the domain controller the watermark came from.
	// Sequence numbers are per-DC and are not replicated, so a watermark is only
	// meaningful against the same incarnation of the same DC.
	DC  string `json:"dc"`
	Inv string `json:"inv,omitempty"`

	// CompletedHigh is the sequence number the last completed enumeration
	// snapshotted. The next one starts immediately above it.
	//
	// It is deliberately the snapshot the enumeration *started* with rather than
	// the highest number it saw. An account written while the enumeration was
	// running lands above the snapshot and is therefore picked up next time, at
	// the cost of occasionally re-reporting one - which is free, because applying
	// an account twice is idempotent.
	CompletedHigh int64 `json:"completed_high"`

	// Scope is the hash of the search bases that enumeration ran with.
	//
	// Without this, widening the scope loses accounts permanently and silently:
	// every account newly in scope already has a sequence number below the
	// watermark, so no incremental enumeration would ever return it.
	Scope string `json:"scope"`

	// GroupScope is the hash of the group bases used when membership was last
	// synchronized. A change requires every account's memberships to be rebuilt.
	GroupScope string `json:"group_scope"`
}

type Scope struct {
	// SearchBases are distinguished names whose subtrees are in scope.
	//
	// Provider paths resolve configured bases to AD's canonical distinguished
	// names before using them.
	SearchBases []string
}

type ServerInfo struct {
	// DC is the host name to pass to -Server for every query in the walk.
	DC string `json:"DC"`

	// HighestUSN is the top of this DC's sequence counter. Any write after this
	// point lands above it, which is what bounds the walk.
	HighestUSN int64 `json:"HighestUSN"`

	// InvocationID identifies this DC's incarnation. A change means it was
	// restored from backup and its sequence numbers are no longer comparable.
	// Empty if it could not be read, which is not fatal - it only means that
	// particular check cannot be made.
	InvocationID string `json:"InvocationID"`
}

type UnlockArgs struct {
	UserImmutableID string
}

type User struct {
	SamAccountName    string   `json:"SamAccountName"`
	DistinguishedName string   `json:"DistinguishedName"`
	Name              string   `json:"Name"`
	EmailAddress      string   `json:"EmailAddress"`
	ObjectGUID        string   `json:"ObjectGUID"`
	MemberOf          []string `json:"MemberOf"`
	LockedOut         bool     `json:"LockedOut"`
	WhenChanged       string   `json:"whenChanged"`

	// UserPrincipalName is the logon name, which looks like an email address and
	// usually is one.
	//
	// It is projected because it is the identifier a person actually types.
	// mail is populated by Exchange rather than by account creation, so an
	// on-prem domain without it leaves every account with no email attribute at
	// all - while the UPN is what those same people sign in with and what a
	// federated login carries as its SAML NameID. Storing only mail and
	// sAMAccountName filed such an account under an identifier nobody would enter.
	UserPrincipalName string `json:"UserPrincipalName"`

	// DisplayName, GivenName and Surname are the other places AD keeps a person's
	// name. They are projected because Name alone is a poor answer to the only
	// question the server asks of it - see PersonName.
	DisplayName string `json:"DisplayName"`
	GivenName   string `json:"GivenName"`
	Surname     string `json:"Surname"`

	// USNChanged is this DC's sequence number for the last change to the object.
	// It is the walk's indexed integer range key. Several objects may share the
	// same value, so pagination consumes complete USN ranges rather than treating
	// it as a unique object cursor.
	USNChanged int64 `json:"USNChanged"`

	// Enabled is a pointer so that a query which did not ask for the property is
	// distinguishable from an account AD reported as disabled.
	Enabled *bool `json:"Enabled"`

	// AdminCount is Active Directory's own marker for an administratively
	// privileged account. SDProp stamps it on the built-in Administrator, on
	// krbtgt, and on every member of a protected administrative group - including
	// members that reach one through a nested group, which memberOf does not
	// report at all.
	//
	// A pointer for the same reason Enabled is one, but the absence is read the
	// other way round. AD leaves the attribute unset on an ordinary account, so
	// "no value" and "not asked for" would be the same JSON null;
	// pointReadAttributes coerces it to an integer precisely so that a projection
	// which asked always emits a number, and nil means nobody asked.
	// requireEligibleAccount refuses on nil. See PrivilegeKnown.
	AdminCount *int `json:"AdminCount"`

	// SID is the account's own security identifier, in its S-1-5-21-... string
	// form.
	//
	// Projected for one reason: it carries the domain prefix that turns
	// PrimaryGroupID from a relative identifier into a group this agent can look
	// up. See primaryGroupSID. Reading the prefix off the account rather than off
	// GetADDomain keeps the derivation correct by construction - a primary group
	// is a RID in the account's own domain - and means nothing has to cache a
	// domain SID across the requests an enumeration is spread over.
	SID string `json:"SID"`

	// PrimaryGroupID is the relative identifier of the account's primary group.
	//
	// Active Directory does not list the primary group in memberOf, and does
	// not list the account in that group's member attribute either, so this is
	// the only place the membership appears at all. Without it a recovery policy
	// written against a group that is somebody's primary group matches nobody -
	// which fails open for a deny rule.
	//
	// A pointer for the reason Enabled is one: every security principal has a
	// primaryGroupID, so nil means the projection did not ask rather than that
	// the account has no primary group. A live recovery-time read refuses an
	// account it cannot classify; see GetADUserGroupsWithPrimary.
	PrimaryGroupID *int `json:"PrimaryGroupID"`

	// Groups is the membership in MemberOf resolved to the identities the server
	// stores. Excluded from the wire format on purpose: it is filled in from a
	// second query, never parsed out of the first one.
	Groups []Group `json:"-"`
}

type Users []*User