zizmor 1.24.1

Static analysis for GitHub Actions
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

use github_actions_models::common::{Permission, Permissions};

use super::{Audit, AuditLoadError, Job, audit_meta};
use crate::audit::AuditError;
use crate::finding::location::Locatable as _;
use crate::models::AsDocument;
use crate::{
    AuditState,
    finding::{Confidence, Persona, Severity, location::SymbolicLocation},
};

audit_meta!(
    UndocumentedPermissions,
    "undocumented-permissions",
    "permissions without explanatory comments"
);

pub(crate) struct UndocumentedPermissions;

#[async_trait::async_trait]
impl Audit for UndocumentedPermissions {
    fn new(_state: &AuditState) -> Result<Self, AuditLoadError>
    where
        Self: Sized,
    {
        Ok(Self)
    }

    async fn audit_workflow<'doc>(
        &self,
        workflow: &'doc crate::models::workflow::Workflow,
        _config: &crate::config::Config,
    ) -> Result<Vec<crate::finding::Finding<'doc>>, AuditError> {
        let mut findings = vec![];

        // Check workflow-level permissions
        if let Some(finding) = self.check_permissions_documentation(
            &workflow.permissions,
            workflow.location(),
            workflow,
        )? {
            findings.push(finding);
        }

        // Check job-level permissions
        for job in workflow.jobs() {
            let (permissions, job_location) = match job {
                Job::NormalJob(job) => (&job.permissions, job.location()),
                Job::ReusableWorkflowCallJob(job) => (&job.permissions, job.location()),
            };

            if let Some(finding) =
                self.check_permissions_documentation(permissions, job_location, workflow)?
            {
                findings.push(finding);
            }
        }

        Ok(findings)
    }
}

impl UndocumentedPermissions {
    fn check_permissions_documentation<'a>(
        &self,
        permissions: &'a Permissions,
        location: SymbolicLocation<'a>,
        workflow: &'a crate::models::workflow::Workflow,
    ) -> Result<Option<crate::finding::Finding<'a>>, AuditError> {
        // Only check explicit permissions blocks
        let Permissions::Explicit(perms) = permissions else {
            return Ok(None);
        };

        if perms.is_empty() {
            return Ok(None);
        }

        // Check each individual permission for documentation
        let mut finding_builder = Self::finding()
            .severity(Severity::Low)
            .confidence(Confidence::High)
            .persona(Persona::Pedantic);

        let base_location = location.clone().primary();
        let mut has_undocumented = false;

        for (perm_name, perm) in perms {
            if perm_name == "contents" && *perm == Permission::Read {
                // Skip "contents: read" as it's common and self-explanatory
                continue;
            }

            let individual_perm_location = base_location
                .clone()
                .with_keys(["permissions".into(), perm_name.as_str().into()]);

            if !self.has_explanatory_comment(&individual_perm_location, workflow)? {
                finding_builder = finding_builder.add_location(
                    individual_perm_location.annotated("needs an explanatory comment"),
                );
                has_undocumented = true;
            }
        }

        // Only create a finding if there are actually undocumented permissions
        if has_undocumented {
            Ok(Some(finding_builder.build(workflow)?))
        } else {
            Ok(None)
        }
    }

    fn has_explanatory_comment(
        &self,
        location: &SymbolicLocation,
        workflow: &crate::models::workflow::Workflow,
    ) -> Result<bool, AuditError> {
        let document = workflow.as_document();

        // Use the concretize API to get a Location with concrete Feature
        let concrete_location = location.clone().concretize(document).map_err(Self::err)?;

        // Check if there are any meaningful comments
        Ok(concrete_location
            .concrete
            .comments
            .iter()
            .any(|comment| comment.is_meaningful()))
    }
}