Skip to main content

ms_rodc/
lib.rs

1//! **ms-rodc** — Read-Only Domain Controller audit primitives.
2//!
3//! # Why RODCs need their own audit surface
4//!
5//! An RODC has:
6//! * Its own **per-RODC krbtgt account** (`krbtgt_NNNNN`) with its own key.
7//!   A ticket forged with the *domain* krbtgt won't validate at an RODC and
8//!   vice-versa, but forging a TGT with a per-RODC krbtgt key is often
9//!   sufficient to authenticate to services that trust the RODC.
10//! * A **Password Replication Policy** (PRP) — the set of accounts whose
11//!   secrets the RODC is allowed to cache locally. Two attributes drive it:
12//!   - `msDS-RevealOnDemandGroup` (allow list)
13//!   - `msDS-NeverRevealGroup` (deny list)
14//! * A **revealed set** tracking what has actually been cached:
15//!   - `msDS-RevealedList` (constructed, per-RODC list of principals whose
16//!     secrets are cached)
17//!   - `msDS-RevealedUsers` (per-user link to revealing RODCs — inverse)
18//!
19//! Silver-lining detection: if a Tier-0 account (Domain Admins, DA-shaped
20//! service accounts) shows up in an RODC's `msDS-RevealedList`, physical
21//! compromise of that RODC hands the attacker a live secret. If the same
22//! account is missing from `msDS-NeverRevealGroup`, that hole was policy,
23//! not accident.
24//!
25//! # What this crate does
26//!
27//! * [`RodcObject`] — normalize an RODC computer object (`primaryGroupID`
28//!   reported as 521, `msDS-KrbTgtLink` pointing at its per-RODC krbtgt).
29//! * [`per_rodc_krbtgt_dn`] / [`per_rodc_krbtgt_sam`] — build the expected
30//!   name of the per-RODC krbtgt account for a given RODC (or recover one
31//!   from `krbtgt_NNNNN` shape).
32//! * [`RevealAudit`] — cross-reference `msDS-RevealedList` against the tier
33//!   classification of the revealed principals; surface Tier-0 leakage.
34//! * [`ldap_filter_rodc_computers`], [`ldap_filter_krbtgt_all`], and
35//!   friends — ready LDAP filters for enumeration.
36//! * [`is_per_rodc_krbtgt_sam`] — cheap sAMAccountName check
37//!   (`krbtgt_NNNNN` or `krbtgt_<numeric>`).
38//!
39//! # What this crate does not do
40//!
41//! * No LDAP transport (bring your own — `ldap3`, adhammer's raw client).
42//! * No ticket forgery for the per-RODC krbtgt key — that path lives in
43//!   `ms-pac-forge` (once the caller has extracted the per-RODC krbtgt key
44//!   via DCSync or SAMR).
45//! * No Kerberos AP-REQ path to distinguish where a ticket was issued — a
46//!   separate RODC-scoped Kerberos client is future work.
47
48use core::fmt;
49
50/// Well-known primary-group RID that identifies an RODC computer account.
51/// A DC has `primaryGroupID == 516` (Domain Controllers); an RODC has
52/// `primaryGroupID == 521` (Read-Only Domain Controllers).
53pub const PRIMARY_GROUP_RID_RODC: u32 = 521;
54
55/// Well-known primary-group RID for a writable DC.
56pub const PRIMARY_GROUP_RID_DC: u32 = 516;
57
58/// LDAP filter matching every RODC computer object in a domain.
59pub fn ldap_filter_rodc_computers() -> &'static str {
60    "(&(objectCategory=computer)(primaryGroupID=521))"
61}
62
63/// LDAP filter matching every krbtgt account (domain-wide `krbtgt` plus
64/// every per-RODC `krbtgt_NNNNN`). Combined with `msDS-KeyVersionNumber`
65/// this drives krbtgt-rotation audits.
66pub fn ldap_filter_krbtgt_all() -> &'static str {
67    "(sAMAccountName=krbtgt*)"
68}
69
70/// LDAP filter matching a specific per-RODC krbtgt by its numeric suffix.
71pub fn ldap_filter_per_rodc_krbtgt(suffix: u32) -> String {
72    format!("(sAMAccountName=krbtgt_{suffix:05})")
73}
74
75/// Cheap sAMAccountName-shape check. Returns the numeric suffix if `sam`
76/// looks like a per-RODC krbtgt (`krbtgt_NNNNN` — Microsoft always
77/// zero-pads the 5-digit form on RODC provisioning, but we accept any
78/// numeric tail for tolerance).
79pub fn is_per_rodc_krbtgt_sam(sam: &str) -> Option<u32> {
80    let rest = sam.strip_prefix("krbtgt_")?;
81    if rest.is_empty() {
82        return None;
83    }
84    rest.parse::<u32>().ok()
85}
86
87/// Recover a per-RODC krbtgt sAMAccountName from a numeric suffix (matches
88/// what `Install-ADDSReadOnlyDomainControllerAccount` writes).
89pub fn per_rodc_krbtgt_sam(suffix: u32) -> String {
90    format!("krbtgt_{suffix:05}")
91}
92
93/// Recover a per-RODC krbtgt full DN under the domain's `CN=Users` container.
94/// `domain_dn` should be the full defaultNamingContext (e.g.
95/// `DC=corp,DC=local`).
96pub fn per_rodc_krbtgt_dn(suffix: u32, domain_dn: &str) -> String {
97    format!("CN={},CN=Users,{}", per_rodc_krbtgt_sam(suffix), domain_dn)
98}
99
100/// A normalized RODC computer object as consumed from AD.
101#[derive(Debug, Clone, PartialEq, Eq)]
102pub struct RodcObject {
103    /// DN of the RODC computer object.
104    pub dn: String,
105    /// `sAMAccountName` (usually ends with `$`).
106    pub sam_account_name: String,
107    /// DN of the per-RODC krbtgt account, from `msDS-KrbTgtLink`.
108    pub krbtgt_link_dn: String,
109    /// Optional numeric suffix parsed from the linked krbtgt sAMAccountName.
110    pub krbtgt_suffix: Option<u32>,
111    /// `msDS-RevealedList` — DNs of principals whose secrets are cached
112    /// locally on this RODC (constructed attribute).
113    pub revealed: Vec<String>,
114    /// `msDS-RevealOnDemandGroup` — allow-list (principals eligible to be
115    /// cached).
116    pub reveal_on_demand: Vec<String>,
117    /// `msDS-NeverRevealGroup` — deny-list (principals whose secrets must
118    /// never be cached, regardless of the allow-list).
119    pub never_reveal: Vec<String>,
120}
121
122impl RodcObject {
123    /// Construct from raw attribute strings. `krbtgt_link_dn` is expected to
124    /// be a DN whose leaf RDN is `CN=krbtgt_NNNNN`; the numeric suffix is
125    /// parsed opportunistically and left as `None` if the shape doesn't
126    /// match (e.g. a legacy install with a non-standard rename).
127    pub fn from_attrs(
128        dn: impl Into<String>,
129        sam_account_name: impl Into<String>,
130        krbtgt_link_dn: impl Into<String>,
131        revealed: Vec<String>,
132        reveal_on_demand: Vec<String>,
133        never_reveal: Vec<String>,
134    ) -> Self {
135        let dn = dn.into();
136        let sam_account_name = sam_account_name.into();
137        let krbtgt_link_dn = krbtgt_link_dn.into();
138        let krbtgt_suffix = leaf_cn(&krbtgt_link_dn).and_then(is_per_rodc_krbtgt_sam);
139        Self {
140            dn,
141            sam_account_name,
142            krbtgt_link_dn,
143            krbtgt_suffix,
144            revealed,
145            reveal_on_demand,
146            never_reveal,
147        }
148    }
149}
150
151/// Extract the CN value from the leaf RDN of a DN. Returns `None` if the
152/// DN is empty or its leaf isn't a CN.
153fn leaf_cn(dn: &str) -> Option<&str> {
154    let rdn = dn.split(',').next()?.trim();
155    rdn.strip_prefix("CN=").or_else(|| rdn.strip_prefix("cn="))
156}
157
158/// A single audit finding produced by [`RevealAudit`].
159#[derive(Debug, Clone, PartialEq, Eq)]
160pub struct RevealFinding {
161    /// DN of the affected RODC.
162    pub rodc_dn: String,
163    /// DN of the principal whose secret is cached at the RODC.
164    pub principal_dn: String,
165    /// Whether the principal is Tier-0 (as classified by the caller).
166    pub tier: RevealTier,
167}
168
169/// Classification the caller applies to a principal to decide the severity
170/// of its presence on an RODC.
171#[derive(Debug, Clone, Copy, PartialEq, Eq)]
172pub enum RevealTier {
173    /// Domain Admin, Enterprise Admin, Schema Admin, KRBTGT — full-domain
174    /// compromise if the RODC key falls.
175    Tier0,
176    /// Server administrators, service accounts with local admin on Tier-1
177    /// hosts.
178    Tier1,
179    /// End-user workstations and their users.
180    Tier2,
181    /// Unclassified — the caller didn't provide a classification.
182    Unknown,
183}
184
185impl fmt::Display for RevealTier {
186    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
187        match self {
188            RevealTier::Tier0 => f.write_str("tier-0"),
189            RevealTier::Tier1 => f.write_str("tier-1"),
190            RevealTier::Tier2 => f.write_str("tier-2"),
191            RevealTier::Unknown => f.write_str("unknown-tier"),
192        }
193    }
194}
195
196/// Auditor: given a set of RODC objects and a per-principal tier lookup,
197/// return every `(rodc, principal)` pair whose presence in the RODC's
198/// `msDS-RevealedList` warrants attention.
199///
200/// A finding is produced when:
201/// * The principal is classified `Tier0` — always.
202/// * The principal is *any* tier AND appears in the RODC's
203///   `msDS-RevealedList` but is missing from `msDS-NeverRevealGroup` when
204///   it *should* have been denied by the caller's policy. This case is
205///   surfaced with `Unknown` if the caller couldn't classify — the caller
206///   decides whether that matters.
207///
208/// The tier lookup is a closure so callers can back it with whatever they
209/// already have (BloodHound classification, adhammer graph, static list).
210pub struct RevealAudit<'a, F: Fn(&str) -> RevealTier> {
211    pub rodcs: &'a [RodcObject],
212    pub classify: F,
213}
214
215impl<'a, F: Fn(&str) -> RevealTier> RevealAudit<'a, F> {
216    pub fn run(&self) -> Vec<RevealFinding> {
217        let mut out = Vec::new();
218        for rodc in self.rodcs {
219            for principal in &rodc.revealed {
220                let tier = (self.classify)(principal);
221                if matches!(tier, RevealTier::Tier0) {
222                    out.push(RevealFinding {
223                        rodc_dn: rodc.dn.clone(),
224                        principal_dn: principal.clone(),
225                        tier,
226                    });
227                }
228            }
229        }
230        out
231    }
232}
233
234/// Attributes commonly requested when auditing an RODC.
235pub const RODC_AUDIT_ATTRS: &[&str] = &[
236    "sAMAccountName",
237    "distinguishedName",
238    "primaryGroupID",
239    "msDS-KrbTgtLink",
240    "msDS-RevealedList",
241    "msDS-RevealOnDemandGroup",
242    "msDS-NeverRevealGroup",
243    "msDS-RevealedUsers",
244];
245
246/// Attributes commonly requested when auditing a krbtgt account (either
247/// domain-wide or per-RODC).
248pub const KRBTGT_AUDIT_ATTRS: &[&str] = &[
249    "sAMAccountName",
250    "distinguishedName",
251    "msDS-KeyVersionNumber",
252    "pwdLastSet",
253    "msDS-RevealedListBL",
254];
255
256#[cfg(test)]
257mod tests {
258    use super::*;
259
260    #[test]
261    fn per_rodc_krbtgt_naming_roundtrip() {
262        let sam = per_rodc_krbtgt_sam(23179);
263        assert_eq!(sam, "krbtgt_23179");
264        assert_eq!(is_per_rodc_krbtgt_sam(&sam), Some(23179));
265
266        let dn = per_rodc_krbtgt_dn(23179, "DC=corp,DC=local");
267        assert_eq!(dn, "CN=krbtgt_23179,CN=Users,DC=corp,DC=local");
268    }
269
270    #[test]
271    fn per_rodc_krbtgt_shape_rejects_non_rodc_krbtgt() {
272        assert_eq!(is_per_rodc_krbtgt_sam("krbtgt"), None);
273        assert_eq!(is_per_rodc_krbtgt_sam("krbtgt_"), None);
274        assert_eq!(is_per_rodc_krbtgt_sam("krbtgt_notnumeric"), None);
275        assert_eq!(is_per_rodc_krbtgt_sam("something-else"), None);
276    }
277
278    #[test]
279    fn per_rodc_krbtgt_short_suffix_still_matches() {
280        // Some legacy installs use unpadded numeric suffixes; our detector
281        // should tolerate them even if we don't emit them.
282        assert_eq!(is_per_rodc_krbtgt_sam("krbtgt_1"), Some(1));
283        assert_eq!(is_per_rodc_krbtgt_sam("krbtgt_00042"), Some(42));
284    }
285
286    #[test]
287    fn rodc_object_parses_krbtgt_suffix() {
288        let rodc = RodcObject::from_attrs(
289            "CN=RODC01,OU=Domain Controllers,DC=corp,DC=local",
290            "RODC01$",
291            "CN=krbtgt_54321,CN=Users,DC=corp,DC=local",
292            vec!["CN=alice,CN=Users,DC=corp,DC=local".into()],
293            vec![],
294            vec![],
295        );
296        assert_eq!(rodc.krbtgt_suffix, Some(54321));
297        assert_eq!(rodc.revealed.len(), 1);
298    }
299
300    #[test]
301    fn reveal_audit_flags_tier0_leakage() {
302        let rodc = RodcObject::from_attrs(
303            "CN=RODC01,OU=Domain Controllers,DC=corp,DC=local",
304            "RODC01$",
305            "CN=krbtgt_54321,CN=Users,DC=corp,DC=local",
306            vec![
307                "CN=alice,CN=Users,DC=corp,DC=local".into(),
308                "CN=Administrator,CN=Users,DC=corp,DC=local".into(),
309                "CN=svc-web,OU=Services,DC=corp,DC=local".into(),
310            ],
311            vec![],
312            vec![],
313        );
314        let rodcs = vec![rodc];
315
316        let audit = RevealAudit {
317            rodcs: &rodcs,
318            classify: |dn: &str| {
319                if dn.contains("Administrator") {
320                    RevealTier::Tier0
321                } else if dn.contains("svc-web") {
322                    RevealTier::Tier1
323                } else {
324                    RevealTier::Tier2
325                }
326            },
327        };
328        let findings = audit.run();
329        assert_eq!(findings.len(), 1);
330        assert_eq!(findings[0].tier, RevealTier::Tier0);
331        assert!(findings[0].principal_dn.contains("Administrator"));
332    }
333
334    #[test]
335    fn ldap_filters_shape() {
336        assert!(ldap_filter_rodc_computers().contains("primaryGroupID=521"));
337        assert!(ldap_filter_krbtgt_all().contains("krbtgt"));
338        let f = ldap_filter_per_rodc_krbtgt(12);
339        assert_eq!(f, "(sAMAccountName=krbtgt_00012)");
340    }
341
342    #[test]
343    fn well_known_rids() {
344        assert_eq!(PRIMARY_GROUP_RID_RODC, 521);
345        assert_eq!(PRIMARY_GROUP_RID_DC, 516);
346    }
347}